initial commit

This commit is contained in:
equippedcoding-master
2025-09-17 09:37:06 -05:00
parent 86108ca47e
commit e2c98790b2
55389 changed files with 6206730 additions and 0 deletions

View File

@@ -0,0 +1,5 @@
_site
.sass-cache
.jekyll-cache
.jekyll-metadata
vendor

View File

@@ -0,0 +1,31 @@
source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
# bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
gem "jekyll", "~> 4.4.0"
gem "just-the-docs"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
gem "jekyll-feed", "~> 0.12"
end
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
gem "tzinfo", "~> 2.0"
gem "tzinfo-data"
end
# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.2.0", :platforms => [:mingw, :x64_mingw, :mswin]

View File

@@ -0,0 +1,104 @@
GEM
remote: https://rubygems.org/
specs:
addressable (2.8.7)
public_suffix (>= 2.0.2, < 7.0)
base64 (0.2.0)
colorator (1.1.0)
concurrent-ruby (1.3.5)
csv (3.3.2)
em-websocket (0.5.3)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0)
eventmachine (1.2.7)
ffi (1.17.1-x64-mingw-ucrt)
ffi (1.17.1-x86_64-linux-gnu)
forwardable-extended (2.6.0)
http_parser.rb (0.8.0)
i18n (1.14.7)
concurrent-ruby (~> 1.0)
jekyll (4.4.1)
addressable (~> 2.4)
base64 (~> 0.2)
colorator (~> 1.0)
csv (~> 3.0)
em-websocket (~> 0.5)
i18n (~> 1.0)
jekyll-sass-converter (>= 2.0, < 4.0)
jekyll-watch (~> 2.0)
json (~> 2.6)
kramdown (~> 2.3, >= 2.3.1)
kramdown-parser-gfm (~> 1.0)
liquid (~> 4.0)
mercenary (~> 0.3, >= 0.3.6)
pathutil (~> 0.9)
rouge (>= 3.0, < 5.0)
safe_yaml (~> 1.0)
terminal-table (>= 1.8, < 4.0)
webrick (~> 1.7)
jekyll-feed (0.17.0)
jekyll (>= 3.7, < 5.0)
jekyll-include-cache (0.2.1)
jekyll (>= 3.7, < 5.0)
jekyll-sass-converter (2.2.0)
sassc (> 2.0.1, < 3.0)
jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
json (2.10.1)
just-the-docs (0.10.1)
jekyll (>= 3.8.5)
jekyll-include-cache
jekyll-seo-tag (>= 2.0)
rake (>= 12.3.1)
kramdown (2.5.1)
rexml (>= 3.3.9)
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.4)
listen (3.9.0)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.4.0)
minima (2.5.2)
jekyll (>= 3.5, < 5.0)
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (5.1.1)
rake (13.2.1)
rb-fsevent (0.11.2)
rb-inotify (0.11.1)
ffi (~> 1.0)
rexml (3.4.0)
rouge (3.30.0)
safe_yaml (1.0.5)
sassc (2.4.0)
ffi (~> 1.9)
terminal-table (1.8.0)
unicode-display_width (~> 1.1, >= 1.1.1)
tzinfo (2.0.6)
concurrent-ruby (~> 1.0)
tzinfo-data (1.2025.1)
tzinfo (>= 1.0.0)
unicode-display_width (1.8.0)
wdm (0.2.0)
webrick (1.9.1)
PLATFORMS
x64-mingw-ucrt
x86_64-linux
DEPENDENCIES
jekyll (~> 4.4.0)
jekyll-feed (~> 0.12)
just-the-docs
minima (~> 2.5)
tzinfo (~> 2.0)
tzinfo-data
wdm (~> 0.2.0)
BUNDLED WITH
2.4.14

View File

@@ -0,0 +1,31 @@
# PCUI-Graph Docs Guide
The PCUI-Graph documentation website is built using a Jekyll template. The markdown pages for the site can be found and edited in the `docs/pages` directory.
The docs site also makes use of Storybook to display React components. If you are developing the PCUI library, you should use `npm run storybook` directly to generate the storybook. The following guide is for updating and publishing the documentation site.
### Developing Docs Locally
Ensure you have Ruby 3.x installed. Go [here](https://rubyinstaller.org/downloads/) for a Windows installer.
To install the Ruby dependencies, run:
cd docs
bundle install
cd ..
If you are having trouble with the install, try deleting the `Gemfile.lock` file.
You are now able to build the site:
npm run build:docsite:local
To view the built site, run:
npm run serve:docs
Open your browser and visit: http://localhost:3000/
### Publishing Docs
The PCUI-Graph docs site is automatically redeployed one every commit to the `main` branch.

View File

@@ -0,0 +1,60 @@
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
#
# If you need help with YAML syntax, here are some quick references for you:
# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
# https://learnxinyminutes.com/docs/yaml/
#
# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via {{ site.myvariable }}.
title: PCUI-Graph
email: support@playcanvas.com
description: >- # this means to ignore newlines until "baseurl:"
PCUI-Graph - PCUI extension for node-based graphs
baseurl: "/pcui-graph" # the subpath of your site, e.g. /blog
url: "https://playcanvas.github.io" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: playcanvas
github_username: playcanvas
# Build settings
theme: "just-the-docs"
color_scheme: pcui
plugins:
- jekyll-feed
aux_links:
"PCUI-Graph on GitHub":
- "//github.com/playcanvas/pcui-graph"
# Exclude from processing.
# The following items will not be processed, by default.
# Any item listed under the `exclude:` key here will be automatically added to
# the internal "default list".
#
# Excluded items can be processed by explicitly listing the directories or
# their entries' file path in the `include:` list.
#
exclude:
- .sass-cache/
- .jekyll-cache/
- gemfiles/
- Gemfile
- Gemfile.lock
- node_modules/
- vendor/bundle/
- vendor/cache/
- vendor/gems/
- vendor/ruby/
- create-component-pages.js
- README.md

View File

@@ -0,0 +1,60 @@
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
#
# If you need help with YAML syntax, here are some quick references for you:
# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
# https://learnxinyminutes.com/docs/yaml/
#
# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via {{ site.myvariable }}.
title: PCUI-Graph
email: support@playcanvas.com
description: >- # this means to ignore newlines until "baseurl:"
PCUI-Graph - PCUI extension for node-based graphs
baseurl: "/" # the subpath of your site, e.g. /blog
url: "http://localhost:3497" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: playcanvas
github_username: playcanvas
# Build settings
theme: "just-the-docs"
color_scheme: pcui
plugins:
- jekyll-feed
aux_links:
"PCUI-Graph on GitHub":
- "//github.com/playcanvas/pcui-graph"
# Exclude from processing.
# The following items will not be processed, by default.
# Any item listed under the `exclude:` key here will be automatically added to
# the internal "default list".
#
# Excluded items can be processed by explicitly listing the directories or
# their entries' file path in the `include:` list.
#
exclude:
- .sass-cache/
- .jekyll-cache/
- gemfiles/
- Gemfile
- Gemfile.lock
- node_modules/
- vendor/bundle/
- vendor/cache/
- vendor/gems/
- vendor/ruby/
- create-component-pages.js
- README.md

View File

@@ -0,0 +1 @@
$link-color: #2aa198;

View File

@@ -0,0 +1,18 @@
html, body, .main, .main-content, .component-iframe {
height: 100% !important;
}
.component-iframe {
width: 100%;
border: none;
margin-left: -20px;
opacity: 0;
}
.main-content-wrap {
height: calc(100% - 60px) !important;
}
.example-background {
background-color: #364346 !important;
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 562 KiB

View File

@@ -0,0 +1,12 @@
---
# Feel free to add content and custom Front Matter to this file.
# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
layout: home
---
# PCUI-Graph - Node-based Graphs Made Easy
![PCUI splash](assets/pcui-graph-banner.png)
PCUI-Graph is an extension of PCUI. It provides an simple API for creating node-based graphs that can be easily integrated with any PCUI application.

View File

@@ -0,0 +1,9 @@
---
layout: page
title: API
permalink: /api/
---
# API
The graph API can be used to programmatically interact with a graph you have instantiated. You can control the view of the graph using the translate / scale functions as well as create / delete / update graph nodes and edges. The full API is documented [here](https://api.playcanvas.com/modules/PCUIGraph.html).

View File

@@ -0,0 +1,18 @@
---
layout: page
title: Config Options
permalink: /config-options/
---
# Config Options
Options can be passed to the graph constructor as a JSON object which change the default behavior of the graph. You can do so as follows:
```javascript
const graph = new Graph(schema, {
readOnly: true,
initialData: { ... }
});
```
You can see a full list of options [here](https://api.playcanvas.com/classes/PCUIGraph.Graph.html#constructor).

View File

@@ -0,0 +1,70 @@
---
layout: page
title: Context Menus
permalink: /context-menus/
---
# Context Menus
It is possible to create context menus on your graph which display when right clicking various graph items. There are three types of context menus; background, node and edge. You can define a set of actions which will display in each of these menus and each action item in the menu will fire an action event when selected.
The background context menu appears when you right click on any blank space in the canvas. This context menu is used to add new nodes to the graph. It can be created by adding a `contextMenuItems` array to the options object passed to the graph constructor:
```javascript
const graph = new Graph(schema, {
contextMenuItems: [
{
{
text: 'Add a hello node',
action: GRAPH.GRAPH_ACTIONS.ADD_NODE,
nodeType: NODE_KEYS.HELLO,
attributes: {
name: 'New hello'
'Editable boolean': true
}
},
{
text: 'Add a world node',
action: GRAPH.GRAPH_ACTIONS.ADD_NODE,
nodeType: NODE_KEYS.WORLD,
attributes: {
name: 'New world'
'Editable boolean': true
}
}
}
]
})
```
The text property defines the display text of the context menu item. The action property tells the graph that this context menu item should fire an `ADD_NODE` action when it is selected. The other properties define the type of node that will be created when this item is selected. The node type references one of the node keys defined in the graphs schema. The attributes object defines the initial values of any editable attributes that exist in that nodes schema. The name attribute will also show up in the header for the node.
Context menus can also be added to nodes and edges by including contextMenu properties in their schemas as follows:
```javascript
const schema = {
edges: {
0: {
contextMenuItems: [
{
text: 'Delete edge', // name of the context menu item
action: Graph.GRAPH_ACTIONS.DELETE_EDGE // action to carry out when item is selected
}
]
}
}
};
```
Currently node context menus support two actions:
``` javascript
Graph.GRAPH_ACTIONS.DELTE_NODE // Delete the node associated with this context menu.
Graph.GRAPH_ACTIONS.ADD_EDGE // Add an edge that starts from the node associated with this context menu, selecting another node will complete the edge connection. Selecting the background canvas will cancel adding an edge.
```
While edges support their own deletion by adding this action in their context menu:
``` javascript
Graph.GRAPH_ACTIONS.DELETE_EDGE // Delete the edge associated with this context menu.
```

View File

@@ -0,0 +1,92 @@
---
layout: page
title: Events
permalink: /events/
---
# Events
After creating a graph, you can register a callback for various events. This is achieved using the graphs [on function](https://api.playcanvas.com/classes/PCUIGraph.Graph.html#on). The following events are supported:
```javascript
import Graph from '@playcanvas/pcui-graph';
const schema = { ... };
const graph = new Graph(schema);
/*
* @event
* @param {object} args.node - The node that was added
*/
graph.on(Graph.GRAPH_ACTIONS.ADD_NODE, ({ node }) => { ... });
/*
* @event
* @param {object} args.node - The node that was deleted
* @param {object} args.edgeData - The edges contained in the graph
* @param {object} args.edges - The edges that were removed when deleting this node
*/
graph.on(Graph.GRAPH_ACTIONS.DELETE_NODE, ({ node, edgeData, edges }) => { ... });
/*
* @event
* @param {object} args.node - The node that was selected
* @param {object} args.prevItem - The previously selected item, either a node or an edge
*/
graph.on(Graph.GRAPH_ACTIONS.SELECT_NODE, ({ node, prevItem }) => { ... });
/*
* @event
* @param {object} args.node - The node that was updated
* @param {object} args.nodeId - The node id of the node that was updated
*/
graph.on(Graph.GRAPH_ACTIONS.UPDATE_NODE_POSITION, ({ node, nodeId }) => { ... });
/*
* @event
* @param {object} args.node - The node that was updated
* @param {object} args.attribute - The name of the attribute that was updated
* @param {object} args.attributeKey - The key of the attribute that was updated
*/
graph.on(Graph.GRAPH_ACTIONS.UPDATE_NODE_ATTRIBUTE, ({ node, attribute, attributeKey }) => { ... });
/*
* @event
* @param {object} args.edge - The edge that was updated
* @param {object} args.edgeId - The id of the edge that was updated
*/
graph.on(Graph.GRAPH_ACTIONS.ADD_EDGE, ({ edge, edgeId }) => { ... });
/*
* @event
* @param {object} args.edge - The edge that was updated
* @param {object} args.edgeId - The id of the edge that was updated
*/
graph.on(Graph.GRAPH_ACTIONS.DELETE_EDGE, ({ edge, edgeId }) => { ... });
/*
* @event
* @param {object} args.edge - The edge that was selected
* @param {object} args.prevItem - The previously selected item, either a node or an edge
*/
graph.on(Graph.GRAPH_ACTIONS.SELECT_EDGE, ({ edge, prevItem }) => { ... });
/*
* @event
* @param {object} args.prevItem - The previously selected item, either a node or an edge
*/
graph.on(Graph.GRAPH_ACTIONS.DESELECT_ITEM, ({ prevItem }) => { ... });
/*
* @event
* @param {number} args.pos.x - The x position of the viewport in relation to the graph
* @param {number} args.pos.y - The y position of the viewport in relation to the graph
*/
graph.on(Graph.GRAPH_ACTIONS.UPDATE_TRANSLATE, ({ pos }) => { ... });
/*
* @event
* param {number} args.scale - The current scale of the graph
*/
graph.on(Graph.GRAPH_ACTIONS.UPDATE_SCALE, ({ scale }) => { ... });
```

View File

@@ -0,0 +1,134 @@
---
layout: page
title: Schema
permalink: /schema/
---
# Schema
The schema object is used to define what type of graph you will be initializing. More specifically, it defines which node your graph can contain and how those nodes can be connected together with edges.
It should contain a set of nodes and edges which can be created in the graph. Each node and edge that is defined will need a unique number key which is used to reference that particular part of the schema. In the above example the single edge type defined references the two nodes contained in the schema when defining which node types it can connect. When creating large schemas, it can be useful to define these keys before creating the schema, so they can be easily referenced:
```javascript
const NODE_KEYS = {
HELLO: 0,
WORLD: 1
};
const EDGE_KEYS = {
HELLO_TO_WORLD: 0
};
const schema = {
nodes: {
[NODE_KEYS.HELLO]: {
name: 'Hello',
fill: 'red'
},
[NODE_KEYS.WORLD]: {
name: 'World',
fill: 'green'
}
},
edges: {
[EDGE_KEYS.HELLO_TO_WORLD]: {
from: [NODE_KEYS.HELLO], // this edge can connect nodes of type NODE_KEYS.HELLO
to: [NODE_KEYS.WORLD] // to nodes of type NODE_KEYS.WORLD,
stroke: 'blue'
}
}
};
```
The schemas above are used to created directed graphs, as they define edges which contain `from` and `to` attributes. These attributes tell an edge which nodes they can connect, creating a directed edge from one node to another.
When creating visual programming graphs, nodes are not connected directly. Instead, they contain input and output ports which can be connected together. This will need to be expressed in the schema you create. To achieve this, you can add `inPorts` and `outPorts` attributes to your nodes in the schema. These will define a set of ports which will be created on a given node, specifying which edges can connect those ports.
The schema defined above can be reworked to support port connections as follows:
```javascript
const NODE_KEYS = {
HELLO: 0,
WORLD: 1
};
const EDGE_KEYS = {
HELLO_TO_WORLD: 0
};
const schema = {
nodes: {
[NODE_KEYS.HELLO]: {
name: 'Hello',
fill: 'red',
outPorts: [
{
name: 'output',
type: EDGE_KEYS.HELLO_TO_WORLD
}
]
},
[NODE_KEYS.WORLD]: {
name: 'World',
fill: 'green',
inPorts: [
{
name: 'input',
type: EDGE_KEYS.HELLO_TO_WORLD
}
]
}
},
edges: {
[EDGE_KEYS.HELLO_TO_WORLD]: {
stroke: 'blue'
}
}
};
```
You can see that created ports have a type which defines the edge type each port accepts. Only input and output ports of the same type can be connected together in the graph. Ports also contain a name which will appear next to the port in the graph.
Nodes can also contain editable attributes, which will show up as input fields within them. These attributes can be set in a node as follows:
```javascript
const schema = {
nodes: {
0: {
name: 'Foobar',
attributes: [
{
name: 'Editable boolean',
type: 'BOOLEAN_INPUT'
},
{
name: 'Editable text',
type: 'TEXT_INPUT'
},
{
name: 'Editable number',
type: 'NUMERIC_INPUT'
},
{
name: 'Editable 2D vector',
type: 'VEC2_INPUT'
},
{
name: 'Editable 3D vector',
type: 'VEC3_INPUT'
},
{
name: 'Editable 4D vector',
type: 'VEC4_INPUT'
}
]
}
}
};
```
Editable attributes for a given node type must have unique names as they are stored in the graph data in a dictionary. When a node with an editable attribute is created, it can be accessed via the graph data as follows:
```javascript
const selectedItemId = graph.selectedItem.id;
const currentBooleanValue = graph.data.nodes[selectedItemId].attributes['Editable boolean'].value;
```

View File

@@ -0,0 +1,11 @@
---
layout: page
title: Storybook
permalink: /storybook-docs/
---
# Storybook
The storybook showcases PCUI-Graph's Graph component in a number of different contexts.
[Click here](../storybook/) to view the storybook.

View File

@@ -0,0 +1,45 @@
---
layout: page
title: Styling
permalink: /styling/
---
# Styling
You can style your graph by overriding it's default style properties. This can be achieved by modifying the defaultStyles passed in as part of an options object to the graph constructor.
```javascript
const graph = new Graph(schema, {
defaultStyles: {
background: {
color: 'black'
}
}
})
```
The defaultStyles object contains styling options for the graphs background as well as node and edge styles. A full list of these overridable properties can be see [here](https://github.com/playcanvas/pcui-graph/blob/main/src/constants.js).
If you'd like to update the styling of particular node / edge types, you can override any of the node or edge properties given in the defaultStyles object by defining them in the schema for a particular node or edge as follows:
```javascript
const schema = {
nodes: {
0: {
name: 'standard node'
},
1: {
name: 'red node'
fill: 'red' // Update the background color of any nodes of this type to red
},
}
};
const graph = new Graph(schema, {
defaultStyles: {
node: {
fill: 'grey' // All other node types will have a grey background
}
}
})
```