develop

beta

rnbw.dev

v0.1

edit
2024 march

in rnbw, your design is your code, and your code is your design. you can develop not just inside rnbw but also for rnbw to enhance it with the desired feature. 

you can create custom actions and extensions that improve or extend rnbw's ux. all of this becomes possible with the help of the rnbw apis.

9.1 api

rnbw apis supports various operation on rnbw which are related to project files, node tree, and code view. you can get the details like current open file, or open an existing file.

find the current selected node, and much more. you can use the different apis together to expand the limits of what you can do with rnbw.

As rnbw is built on top of react and typescript, therefore APIs in rnbw are exposed via react custom hook. As rnbw APIs are react custom hooks, so they can be consumed only in a react component or another react custom hook.

To get access to rnbw APIs all you need to do is: 

const rnbw = useRnbw()

9.1.1 files

Every files in rnbw consists of a tree of folders and files. at the root of every files is a folder node, and from that node stems sub folder or files.

Files have a number of properties associated with them. some of these are global properties, that exist on every file, whereas other file properties will be specific to the type of file or folder.

example
create

Creates a new file with the provided name and extension. 

params: An object containing the following properties

  • entityName: (string) - The name of the file. Defaults to "untitled" if no value is passed.
  • extension: (string) - Extension for the file. Defaults to "html" if no value is passed.
rnbw.files.createFile(params)
Example
rnbw.files.createFile("about", "html")

Creates a new folder with the provided name. If no name is provided the default folder name is `untitled`.

params: An object containing the following properties

  • entityName: (string) - The name of the file. Defaults to "untitled" if no value is passed.
rnbw.files.createFolder(params)
Example
rnbw.files.createFolder("styles")
read

Returns the tree of the files in the folder that is opened currently in "rnbw".

rnbw.files.getRootTree()
Example
rnbw.files.getRootTree()
Output
{   
 ROOT:{  
   uid:'ROOT',                                
   parentUid: null,     
   name: 'rainbw',
   isFile: false,
   children: [
    'ROOT/index.html',
    'ROOT/index.js',
    'ROOT/styles.css',
   ],
   url: '/rnbw',
  },
 'ROOT/index.html': {
   ...
  },
 'ROOT/index.js': {
  ...
  },
  'ROOT/styles.css': {
  ...
  }
}

Returns the details of the Folder whose uid is passed

params: An object containing the following properties

  • uid: (string) - The uid of the file.
rnbw.files.getFolderTree(params)
Example
rnbw.files.getFolderTree("ROOT/styles")
Output
'ROOT/styles': {
    uid: 'ROOT/styles',
    parentUid: 'ROOT',
    name: 'styles',
    isFile: false,
    children: [
        'ROOT/styles/footer.css',
        'ROOT/styles/navbar.css'
    ],
    url: '/rainbow/styles',
}

Returns the current file details

rnbw.files.getCurrentFile()
Example
rnbw.files.getCurrentFile() //Assuming index.html is the current file
Output
'ROOT/index.html': {
    uid: 'ROOT/index.html',
    parentUid: 'ROOT',
    name: 'index',
    isFile: true,
    url: '/rainbow/index.html',
    extension:'html',
    content: 'content of the file currently',
},

Sets the `rnbw's clipboard state` with the uids passed along with the type as "copy".

params: An object containing the following properties

  • uids: (string [ ]) - The uids of the files. Defaults to selected files uids if no uids are passed.
rnbw.files.copyFiles(params)
Example
rnbw.files.copyFiles({
uids: ['ROOT/index.html',
        'ROOT/about.html']
 })
Output
clipboardData: {
        panel: 'file',
        type: 'copy',
        uids: [
          'ROOT/index.html',
          'ROOT/about.html'
        ]
      },

Sets the `rnbw's clipboard state` with the uids passed along with the type as "cut".

params: An object containing the following properties

  • uids: (string [ ]) - The uids of the files. Defaults to selected files uids if no uids are passed.
rnbw.files.cutFiles(params)
Example
rnbw.files.cutFiles({
uids: ['ROOT/index.html',
        'ROOT/about.html']
 })
Output
clipboardData: {
        panel: 'file',
        type: 'cut',
        uids: [
          'ROOT/index.html',
          'ROOT/about.html'
        ]
      },

Returns the uids of the selected files and directories in the file tree

rnbw.files.getSelectedFiles()
Example
rnbw.files.getSelectedFiles()
Output
['ROOT/styles/footer.css',
 'ROOT/styles/navbar.css']
update

Sets the file whose uid is passed as the  current active file.

params: An object containing the following properties

  • uid: (string) - The uid of the file.
rnbw.files.setCurrentFile(params)
Example
rnbw.files.setCurrentFile({
uid:'ROOT/about.html'
})

Updates the content of the current file with the content that is passed.

params: An object containing the following properties

  • content: (string) - The content is going to be string that we want to update our file with.
rnbw.files.setCurrentFileContent(params)
Example
rnbw.files.setCurrentFileContent({
content:'
<html>
<body>
<p> hello rnbw </p>
</body>
</html>')

Renames the file or folder with the name provided.

params: An object containing the following properties

  • uid: (string) - The uid of the file.
  • newName: (string) - The new name of the file.
  • extension: (string) - Extension for the file.
rnbw.files.rename(params)
Example
rnbw.files.rename({
uid:'ROOT/about.html',
newName:'about-us',
extension:'html'
})

Undo the state of the files one step at a time.

rnbw.files.undo()
Example
rnbw.files.undo()

Redo the state of the files one step at a time.

rnbw.files.redo()
Example
rnbw.files.redo()

Pastes the copied or cut files and folders to the location of the "destination Uid"

params: An object containing the following properties

  • uids: (string) - The uids of the file to be pasted
  • targetUid: (string) - The uid of the file or folder where it will be pasted. Defaults to selected file uid.
  • deleteSource: (boolean) - if it's true then the original files are deleted after copying. Defaults to false.
rnbw.files.paste(params)
Example
rnbw.files.paste({
uids:["ROOT/styles","ROOT/js/index.js"],
targetUid: "ROOT/src",
deleteSource: false
})

Moves the file(s) or folder(s) that are currently selected to the passed destination id.

params: An object containing the following properties

  • uids: (string) - The uids of the file to be moved
  • targetUid: (string) - The uid of the file or folder where it will be pasted. Defaults to selected file uid.
rnbw.files.move(params)
Example
rnbw.files.move({
uids:["ROOT/styles","ROOT/js/index.js"],
targetUid: "ROOT/src",
})
delete

deletes the selected file(s) or folder(s).

params: An object containing the following properties

  • uids: (string) - The uids of the file to be removed
rnbw.files.remove(params)
Example
rnbw.files.remove({
uids:[
'ROOT/about.html',
'ROOT/contact.html']
})

9.1.1 elements

Whenever an HTML file is opened in rnbw, a node tree is created.

example
create

Adds a specified HTML element or comment tag to the code view based on the provided parameters.

params: An object containing the following properties

  • tagName: (string) The name of the HTML tag to be added.
  • skipUpdate: (boolean - optional) - If true, the code view will not be updated after adding the element. Default is false.

Returns the updated code, if successful. 

rnbw.elements.add(params)
Example
const result: string = rnbw.elements.add
({  tagName: 'div'});

Adds a copy of the selected html element as the child of the selected element's parent. 

params: An object containing the following properties (optional):

  • skipUpdate: (boolean - optional) - If true, the code view will not be updated after duplicating the element. Default is false.

Returns the updated code, if successful.

rnbw.elements.duplicate(params)
Example
const result: string = rnbw.elements.duplicate()
read

returns the details of the element whose uid is passed

params: 

  • uid: (string) - uid of the element whose detail is required.
rnbw.elements.getElement(elementUid)
Example
rnbw.elements.getElement("761")
Output
{
  uid: "62",
  parentUid: "40",
  name: "div",
  children: ["114", "115", "116", "117", "118"],
  tagName: "div",
  textContent: "",
  attribs: {
    class: "page gap-xl",
    id: "code",
  },
  sourceCodeLocation: {
    startLine: 714,
    startCol: 9,
    startOffset: 36632,
    endLine: 728,
    endCol: 15,
    endOffset: 37258,
    startTag:{...},
    endTag: {...}
  },
}

Returns the "uids" of the elements selected on the stage.

rnbw.elements.getSelectedElements()
Example
rnbw.elements.getSelectedElements()
Output
["761","854"]

Returns the settings object of the elements whose uid is passed.

params: 

  • uid: (string) - uid of the element whose detail is required. Defaults to selected element.
rnbw.elements.getElementSettings()
Example
rnbw.elements.getElementSettings()
Output
{
class:"box column"
style: "border: 1px solid white"
}

Copies the code of items in the code view to the clipboard. Optionally, it can update the clipboard with the copied code.

If multiple elements are selected then the elements are sorted by their "uid (unique Id)". And then the codes are joined together and copied to the system clipboard.

params: An object containing the following properties (optional):

  • uids: (string[ ] - optional) - An array of unique identifiers (UIDs) of the selected items. If not provided, defaults to the currently selected items.
  • skipUpdate: (boolean - optional) - If true, the clipboard will be updated with the code of the copied element.

Returns the copied code, if successful.

rnbw.elements.copy(params)
Example
rnbw.elements.copy()
update

Selects the elements whose uids are passed replacing the existing selected elements.

If the uids passed doesn't exist then it does nothing.

rnbw.elements.setSelectedElements(elementsUid)
Example
rnbw.elements.setSelectedElements(["215","456"])

Cuts the selected element.

Returns the cut code, and the updated code after cut, if successful.

rnbw.elements.cut()
Example
rnbw.elements.cut()

Pasted the cut or copied elements at a specified position with respect to the selected element.

params: An object containing the following properties (optional):

  • content: (string - optional) - The content to be pasted. If not provided, the content will be retrieved from the clipboard.
  • skipUpdate: (boolean - optional) - If true, the code view will not be updated after pasting the content. Default is false.
  • pastePosition: (string - optional) - Specifies where to paste the content in relation to the target node. Possible values are "before", "after", or "inside". Default is "after".
  • targetUid: (string - optional) - The unique identifier (UID) of the target node. If not provided, the focused node will be the target node.
  • pasteContent: (string - optional). The content to be pasted. If provided, it takes precedence over the clipboard content.
rnbw.elements.paste(params: Ipaste = {})
Example
const result: Promise<string> = paste();

groups the selected elements by wrapping them in a <div> container.

params: an object containing the following properties (optional):

  • uids: (string[ ] - optional) - An array of unique identifiers (UIDs) of the selected items. If not provided, defaults to the currently selected items.
  • skipUpdate: (boolean - optional) - If true, the code view will not be updated after adding the element. Default is false.

Returns the updated code, if successful.

rnbw.elements.group(params)
Example
rnbw.elements.group()

Ungroups the selected elements.

params: An object containing the following properties (optional):

  • uids: (string[ ] - optional) - An array of unique identifiers (UIDs) of the selected items. If not provided, defaults to the currently selected items.
  • skipUpdate: (boolean - optional) - If true, the code view will not be updated after adding the element. Default is false.

Returns the updated code, if successful.

rnbw.elements.ungroup(params)
Example
rnbw.elements.ungroup()

Moves the selected elements inside the target element based on the position.

params: An object containing the following properties:

  • targetUid: (string) The unique identifier (UID) of the target node where the selected nodes will be moved.
  • skipUpdate: (boolean -optional) - If true, the code view will not be updated after pasting the content. Default is false.
  • isBetween: (boolean) Specifies whether the target position is between nodes or inside a parent node.
  • position: (number) The position index where the selected nodes will be moved.
  • selectedUids: (string[ ]) An array of unique identifiers (UIDs) of the selected nodes to be moved.
rnbw.elements.move(params)
Example
rnbw.elements.move({
  targetUid: '202',
  isBetween: true,
  position: 2,
  selectedUids: ['356', '357', '358x']
});

Updates the setting of the selected element. Attributes for the elements are passed in the form of key value pairs.

params: An object containing the following properties:

  • settings: An object representing the settings to be updated. Each key-value pair corresponds to an attribute name and its new value.
  • skipUpdate: (boolean -optional). If true, the code view will not be updated after pasting the content. Default is false.

Returns:

  • isSuccess: true/false
  • settings (updated settings object)
  • code (updated code)
rnbw.elements.updateSettings(params)rnbw.elements.updateSetting({
settings:{
class:"box column",
id:"hero-section"
}})

Undo the state of the elements by 1 step.

rnbw.elements.undo()
Example
rnbw.elements.undo()

Redo the state of the elements by 1 step.

rnbw.elements.redo()
Example
rnbw.elements.redo()
delete

Deletes the elements whose uids are passed.

params: An object containing the following properties:

  • uids: (string [ ] - optional)- uids of the elements to be removed. Defaults to selected element.
  • skipUpdate: (boolean - optional) - If true, the code view will not be updated after removing the selected elements. Default is false.

Returns the updated code, if successful.

rnbw.elements.remove(params)
Example
rnbw.elements.remove({
uids:["261","351","401"],
skipUpdate:false
})

9.2 actions

in rnbw, your design is your code, and your code is your design. you can develop not just inside rnbw but also for rnbw to enhance it with the desired feature. 

you can create custom actions and extensions that improve or extend rnbw's ux. all of this becomes possible with the help of the rnbw apis.

To compose the actions we use the rnbw APIs which are exposed via useRnbw custom hook. As hooks can be used either in a React component or a react custom hook so actions are also react custom hooks.

There are two types of actions - internal and external. Internal actions are those which are developed by rnbw team and external actions are developed by the contributors of rnbw.

9.2.1 find action purpose

Think of a use case which you think will enhance your experience with rnbw. It can be related to something you want to do with your html content or something with the files.

//action examples

Remove all the attributes from an element
or
Remove all the empty folders in a project

9.2.2 create a custom hook

All the actions reside inside the "action" folder in the root of the "rnbw". Now head to the actions directory inside rnbw and create a custom hook file for you action.

//syntax
rnbw > actions > use<action>.action.tsx

//example
rnbw > actions > useRemoveAllAttributes.action.tsx

9.2.3 define the action

Each action returns a config.The config contains following things:

  • name: the name of the action
  • execute: a function that performs the operation expected from the action. Get everything you need perform your action using the rnbw api.
  • description: a short description about what the action does.
  • shortcuts: provides a list of shortcuts that can trigger the action if all the condition are for it to trigger are met. 
export default function useTurnInto() {    
const rnbw = useRnbw();  
const selectedElements =   
rnbw.elements.getSelectedElements();
  function turnInto(tagName: string) {
     /*perform all the steps 
      the get the desired results.*/
  }

  const config = {
    name: "Turn Into",
    execute: turnInto,
    description: "Turn selected 
    elements into a new tag",
    shortcuts: ["cmd+shift+t"],
  };

  return config;
}

9.2.4 using actions

you can use your custom action similar to any react custom hook in rnbw. 

const action = useTurnInto()
const actionName = action.name
const execute = action.execute
const description = action.description
const shortcuts = action.shortcuts

9.3 extensions

extensions are created by the rnbw community to extend the functionality of rnbw. extensions can be as simple as showing some information or can be used to perform one or more actions.

users and organisations can use the power of extensions to customize and enhance their experience to create more efficient workflows.

9.4 contribute

a big welcome and thank you for considering contributing to rainbow! contributions are always welcome, and you can quickly get your fix or improvement slated for the next release.

the contributors’ community can be found on github discussions where you can ask questions, voice ideas, and share your projects.