@bbx-audio/nectar


> Collection of JUCE-y modules for building web-based plugin GUIs 🧃

Overview

nectar is primarily a TypeScript wrapper around the JUCE javascript code that is used for building WebView-based GUIs.
It also contains a number of other classes and utilities for things like parameter management, event handling, errors, and math.

This library is framework-agnostic, so feel free to use it in _any_ web-based project 🍻

Installation

``bash


NPM

npm i @bbx-audio/nectar

Yarn

yarn add @bbx-audio/nectar
`

Usage

Please refer to the documentation for a comprehensive overview of this library.

$3

The juce module contains code that needs to be
executed early in your program so that the communication with the JUCE backend is initialized properly.

This is done by simply adding an extra import statement to the top of your frontend's entrypoint file:
`typescript
// In an entrypoint file e.g., main.ts or index.ts

import '@bbx-audio/nectar/init'
`

$3

The error module contains the Result type, which generally helps improve error handling.

It does this by wrapping the result of a function call in a structure that either contains
the result as expected or the error that occurred during the function's execution.

`typescript
import { Result } from '@bbx-audio/nectar'

function divide(a: number, b: number): Result {
if (b === 0) {
return [null, new Error('Unable to divide by zero')]
} else {
return [a / b, null]
}
}

const [result, error] = divide(1, 0)
if (error) {
// Handle the error
} else {
// Proceed with the result
}
`

$3

The event module contains a class that allows you to register listener callbacks that are executed when global
window and DOM events are emitted. This has two main benefits:
- Increased performance by limiting the number of actual event listeners to one instead of several since you do not have to add the listeners in each component.
- Improved developer experience by making it easier to subscribe and manage subscriptions to events.

`typescript
import { GlobalEventManager } from '@bbx-audio/nectar'

const unsubscribeToClick = GlobalEventManager.subscribeToClick((event: MouseEvent) => {
// Do something when the mouse is clicked.
})

// Be sure to invoke the unsubscribe closure that we get as a result of subscribing to the event.
unsubscribeToClick()

// You can also subscribe to key-based events.
const unsubscribeToEnterKey = GlobalEventManager.subscribeToKey('Enter', (pressed: boolean, event: KeyboardEvent) => {
if (pressed) {
// Do something when the key is pressed.
} else {
// Do something when the key is not pressed (after being pressed).
}
})

// Cleanup the subscription later.
unsubscribeToEnterKey()
`

$3

The parameter module contains the classes and utilities to properly setup bidirectional communication with the JUCE backend.

#### Parameter Types

There are three different types of parameters:
- Boolean - A yes or no choice, represented by a boolean value internally.
- Choice - A selection among multiple choices, represented by an integer value internally.
- Float - A decimal number, represented by a float value internally.

You can subscribe to a parameter of any type to register callbacks when its internal value is updated.
This is useful when making sure the UI elements are in-sync with the backend values.

React:

`tsx
import { IBooleanParameter, ParameterChangeSource } from '@bbx-audio/nectar'

interface IToggleButtonProps {
parameter: IBooleanParameter
}

const ToggleButton = ({ parameter }: IToggleButtonProps) => {
const [isToggled, setIsToggled] = useState(parameter.getValue())

useEffect(() => {
const unsubscribe = parameter.subscribe((value, source) => {
if (isToggled !== value) {
setIsToggled(value)
}
})
return () => unsubscribe()
}, [])

function onClick(): void {
parameter.setValue(!isToggled, ParameterChangeSource.Frontend)
}

return (

{isToggled ? 'On' : 'Off'}

)
}
`

Svelte:
`svelte



{isToggled ? 'On' : 'Off'}

`

#### Parameter Manager

The ParameterManager is a global object that handles backend communication for each parameter that is registered with it.
You can register parameters individually or call a special method that loads parameter data from the backend.

:warning: Do NOT call the initializeParameters method to unless the backend has been properly setup to pass parameter
configuration information to the frontend in JSON format.

`tsx
import { ParameterManager, ParameterType } from '@bbx-audio/nectar'

// Create the parameter manager
const manager = new ParameterManager()

// Register a simple boolean parameter for toggling mono on and off
const monoParameter = manager.registerParameter({
id: 'MONO',
name: 'Mono',
type: ParameterType.Boolean,
defaultValue: false,
})

// Pass your mono parameter to a component, like a toggle button
// ...

// Be sure to clean up the manager as well
manager.cleanup()
``

Contributing

This project is open and welcoming of outside contributions! There are multiple ways you can contribute:
- File a bug report if you encounter buggy or erroneous behavior so we can get it fixed ASAP.
- Open a pull request if you have some changes you would like to make to the library. Every pull request MUST be associated with a GitHub issue!