@gorilla-engine-sdk/ge-dialogs-lib

A React dialog library for Gorilla Engine audio plugin interfaces, featuring:

• Blocking and non-blocking modals
• Ready-to-use message, confirmation, and custom-content modal components
• Tooltips positioned from Gorilla Engine native component refs
• Timed notifications with optional stacking
• Shared, customizable styles for all dialog types
• Runtime updates when the plugin UI size changes

This library is designed for Gorilla Engine React, a custom React reconciler that renders to native Gorilla Engine UI components.

Install

npm install @gorilla-engine-sdk/ge-dialogs-lib

Peer dependency: @gorilla-engine-sdk/gorilla-engine-react 1.x

Quick Start

Render Dialogs around every component that uses a dialog hook. The wrapper installs the modal, tooltip, notification, and style contexts and renders their roots above your application content.

import * as React from 'react';
import * as GEReact from '@gorilla-engine-sdk/gorilla-engine-react';
import {
  DefaultModal,
  Dialogs,
  useModal,
  useNotification,
  useToolTip,
} from '@gorilla-engine-sdk/ge-dialogs-lib';

const PLUGIN_WIDTH = 920;
const PLUGIN_HEIGHT = 590;

function PluginUI() {
  const helpButtonRef = React.useRef<any>(null);
  const [showNotification] = useNotification();
  const [showToolTip, hideToolTip] = useToolTip();
  const [showModal, hideModal] = useModal(() => (
    <DefaultModal
      title="Reset settings?"
      message="This restores all settings to their factory values."
      isBlocking
      isBlockingClosable
      closeTrigger
      cancelTrigger
      cancelTriggerLabel="Cancel"
      onCancelTrigger={hideModal}
      approveTrigger
      approveTriggerLabel="Reset"
      onApproveTrigger={() => {
        resetSettings();
        hideModal();
        showNotification({ message: 'Settings reset' });
      }}
    />
  ));

  return (
    <geLabel width={PLUGIN_WIDTH} height={PLUGIN_HEIGHT}>
      <geButton x={20} y={20} width={140} height={32} text="Reset" onClick={showModal} />
      <geButton
        ref={helpButtonRef}
        x={180}
        y={20}
        width={32}
        height={32}
        text="?"
        onMouseEnter={() => showToolTip(helpButtonRef.current, 'Reset help')}
        onMouseExit={hideToolTip}
      />
    </geLabel>
  );
}

function App() {
  return (
    <Dialogs
      styleState={{
        pluginWidth: PLUGIN_WIDTH,
        pluginHeight: PLUGIN_HEIGHT,
      }}
    >
      <PluginUI />
    </Dialogs>
  );
}

GEReact.createUI(<App />, PLUGIN_WIDTH, PLUGIN_HEIGHT);

Modals

useModal

const [showModal, hideModal] = useModal(component, inputs?, isBlocking?, zIndex?);

Registers a function component with the nearest Dialogs or ModalProvider. It returns stable callbacks that show and hide that modal. Class components are not supported.

| Argument | Type | Default | Description | | ------------ | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | component | React.FunctionComponent | | Function component rendered when the modal is shown. | | inputs | React.DependencyList | [] | Values that recreate the registered component when they change. Include every changing value used by the component, or read changing data from a ref. | | isBlocking | boolean | true | Compatibility argument. Set blocking behavior on the rendered Modal or DefaultModal with its isBlocking prop. | | zIndex | string | | Optional registration key. Normally the hook generates one automatically. |

The modal is also removed when the component using the hook unmounts.

DefaultModal

DefaultModal displays a title and message using the shared modal style. It accepts all ModalProps plus a required message string.

const [showError, hideError] = useModal(() => (
  <DefaultModal
    title="Unable to load preset"
    message="The selected preset file could not be read."
    isBlocking
    closeTrigger
    approveTrigger
    approveTriggerLabel="OK"
    onApproveTrigger={hideError}
    onCancelTrigger={hideError}
  />
));

The default cancel and approve labels are Cancel and OK.

Modal

Use Modal directly when the dialog needs custom native content. Children are rendered below the header inside the modal's horizontal content margins.

const [showRename, hideRename] = useModal(() => (
  <Modal
    title="Rename preset"
    modalWidth={420}
    modalHeight={240}
    isBlocking
    closeTrigger
    cancelTrigger
    cancelTriggerLabel="Cancel"
    onCancelTrigger={hideRename}
    approveTrigger
    approveTriggerLabel="Save"
    onApproveTrigger={() => {
      savePresetName();
      hideRename();
    }}
  >
    <geTextEditor x={0} y={20} width={388} height={32} text="New preset name" />
  </Modal>
));

ModalProps

| Property | Type | Description | | ------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- | | title | string | Required title displayed in the modal header. | | modalStyle | ModalsStyle | Complete style override for this modal. | | modalWidth | number | Width override; otherwise the active style's modalWidth is used. | | modalHeight | number | Height override; otherwise the active style's modalHeight is used. | | x, y | number | Absolute position overrides. Alignment rules are used when omitted. | | isBlocking | boolean | Intercepts mouse clicks across the plugin and shows the blocking background. | | isBlockingClosable | boolean | Calls onCancelTrigger when the blocking background is clicked. | | blockingBackgroundColor | string | Per-modal blocking background color override. | | closeTrigger | boolean | Shows the header close button. It calls onCancelTrigger. | | cancelTrigger | boolean | Shows the footer cancel button. | | cancelTriggerEnabled | boolean | Enables or disables the cancel button. | | cancelTriggerLabel | string | Cancel button text. | | onCancelTrigger | () => void | Handles close, cancel, and closable-background actions. Call hideModal here when the modal should close. | | approveTrigger | boolean | Shows the footer approve button. | | approveTriggerEnabled | boolean | Enables or disables the approve button. | | approveTriggerLabel | string | Approve button text. | | onApproveTrigger | () => void | Handles approval. Call hideModal here when the modal should close. | | children | ReactNode | Custom Gorilla Engine React content. |

Tooltips

useToolTip

const [showToolTip, hideToolTip] = useToolTip(options?);

showToolTip(component, text, style?) displays a tooltip after the configured delay. Pass the native component instance from a ref, not a browser element. The tooltip is centered below the target when space permits and moves above it near the bottom edge of the plugin.

const buttonRef = React.useRef<any>(null);
const [showToolTip, hideToolTip] = useToolTip();

<geButton
  ref={buttonRef}
  width={32}
  height={32}
  text="?"
  onMouseEnter={() => showToolTip(buttonRef.current, 'Open the user guide')}
  onMouseExit={hideToolTip}
/>;

The optional hook-level toolTipStyle applies to every tooltip from that hook. The style passed to showToolTip takes precedence over the hook-level and global styles.

Notifications

useNotification

const [showNotification, hideNotification] = useNotification(options?);

Show a notification by passing a message and, optionally, a complete notification style override:

const [showNotification] = useNotification();

showNotification({ message: 'Preset saved successfully' });

showNotification({
  message: 'Could not save preset',
  notificationStyle: {
    ...dialogsDefaultStyle.notification!,
    container: {
      ...dialogsDefaultStyle.notification!.container,
      backgroundColor: '9E2A2B',
    },
  },
});

Notifications dismiss automatically after notification.duration milliseconds. The default duration is 2500 ms. Multiple active notifications render together; setting stackNotifications enables offset stacking.

The hook also returns hideNotification for API compatibility. Current notification identifiers are generated internally, so normal integrations should rely on automatic dismissal.

Styling

Pass a DialogsStylesState object to Dialogs. Only pluginWidth and pluginHeight are required; omitted modal, tooltip, and notification sections fall back to dialogsDefaultStyle.

When customizing a section, derive it from the defaults because each supplied section is treated as a complete style object rather than deep-merged.

import {
  Dialogs,
  DialogsStylesState,
  dialogsDefaultStyle,
} from '@gorilla-engine-sdk/ge-dialogs-lib';

const dialogStyles: DialogsStylesState = {
  ...dialogsDefaultStyle,
  pluginWidth: 920,
  pluginHeight: 590,
  modal: {
    ...dialogsDefaultStyle.modal!,
    modal: {
      ...dialogsDefaultStyle.modal!.modal,
      backgroundColor: '2F333F',
      border: { width: 1, color: '3F4354' },
    },
    approveButton: {
      ...dialogsDefaultStyle.modal!.approveButton,
      backgroundColor: '5177E0',
      textColor: 'FFFFFF',
    },
  },
  notification: {
    ...dialogsDefaultStyle.notification!,
    duration: 3000,
    container: {
      ...dialogsDefaultStyle.notification!.container,
      backgroundColor: '20242E',
    },
  },
  toolTip: {
    ...dialogsDefaultStyle.toolTip!,
    showDelay: 500,
  },
};

<Dialogs styleState={dialogStyles}>
  <PluginUI />
</Dialogs>;

Style State

| Property | Type | Description | | -------------------- | -------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | pluginWidth | number | Width of the full plugin UI and dialog overlay. | | pluginHeight | number | Height of the full plugin UI and dialog overlay. | | modal | ModalsStyle | Modal alignment, dimensions, colors, and component props. | | notification | NotificationsStyle | Notification alignment, duration, container, and label props. | | toolTip | ToolTipsStyle | Tooltip delay, container, and label props. | | stackNotifications | { direction: 'up' | 'down' } | Enables notification stacking. The direction value is reserved for stack configuration. |

All modal, title, message, dividerLine, container, and label style entries accept the corresponding partial Gorilla Engine React component props. Button styles accept partial GEButtonProps.

Updating Plugin Size

If the plugin can resize, update the dialog overlay dimensions from a component inside Dialogs:

import {
  DialogsStylesDispatchTypes,
  useDialogsStylesStateDispatch,
} from '@gorilla-engine-sdk/ge-dialogs-lib';

function ResizeListener({ width, height }: { width: number; height: number }) {
  const dispatch = useDialogsStylesStateDispatch();

  React.useEffect(() => {
    dispatch({
      type: DialogsStylesDispatchTypes.changePluginSize,
      payload: { width, height },
    });
  }, [dispatch, width, height]);

  return null;
}

Use useDialogsStylesState() to read the current style state from descendants.

Default Layout

The exported dialogsDefaultStyle uses a 1024 x 768 plugin area with:

• A centered 400 x 220 modal and translucent blocking background
• Notifications aligned 30 px from the bottom-right corner
• A 400 ms tooltip delay with automatic edge-aware placement
• Native component colors written as Gorilla Engine hex strings without #

Override pluginWidth and pluginHeight to match the dimensions passed to GEReact.createUI.

Exported API

| Export | Purpose | | ------------------------------- | ---------------------------------------------------------------------- | | Dialogs | Recommended top-level provider for all dialog types and shared styles. | | DefaultModal | Message modal built on Modal. | | DefaultModalProps | Props type for DefaultModal. | | Modal | Base modal component for custom content. | | ModalProps | Props type for Modal. | | useModal | Registers and controls a modal function component. | | useToolTip | Shows and hides tooltips anchored to native component refs. | | DefaultToolTip | Default tooltip renderer. Most consumers use it through useToolTip. | | useNotification | Shows timed notifications. | | DialogsStylesState | Shared dialog style-state type. | | DialogsStylesDispatchTypes | Action names for style-state updates. | | useDialogsStylesState | Reads the current shared style state. | | useDialogsStylesStateDispatch | Dispatches shared style-state updates. | | dialogsDefaultStyle | Complete default style state. | | ModalProvider | Low-level modal provider used by Dialogs. | | ModalProviderProps | Props type for ModalProvider. | | ErrorBoundary | Native-label error boundary used by the built-in dialog components. | | GE_DIALOGS_LIB | Log prefix constant ([ge-dialogs-lib]). |

For normal application setup, prefer Dialogs over constructing the individual providers yourself.

Error Handling

Calling a hook outside its provider throws an error. In practice, ensure the hook is called by a descendant of Dialogs, not by the same component that returns the Dialogs wrapper.

The built-in modal, tooltip, and notification components use ErrorBoundary. If rendering fails, it logs the error and replaces that dialog with a native <geLabel> containing error information.

License

GORILLA ENGINE FREE TIER LICENSE