@bpmn-io/properties-panel 0.13.0 → 0.14.0

package/dist/index.js

@@ -161,6 +161,7 @@ function Header(props) {
         rel: "noopener",
         class: "bio-properties-panel-header-link",
         href: documentationRef,
+        title: "Open documentation",
         target: "_blank",
         children: jsxRuntime.jsx(ExternalLinkIcon, {})
       }) : null
@@ -173,480 +174,6 @@ const DescriptionContext = preact.createContext({
   getDescriptionForId: () => {}
 });
 
-var FN_REF = '__fn';
-var DEFAULT_PRIORITY$1 = 1000;
-var slice = Array.prototype.slice;
-/**
- * A general purpose event bus.
- *
- * This component is used to communicate across a diagram instance.
- * Other parts of a diagram can use it to listen to and broadcast events.
- *
- *
- * ## Registering for Events
- *
- * The event bus provides the {@link EventBus#on} and {@link EventBus#once}
- * methods to register for events. {@link EventBus#off} can be used to
- * remove event registrations. Listeners receive an instance of {@link Event}
- * as the first argument. It allows them to hook into the event execution.
- *
- * ```javascript
- *
- * // listen for event
- * eventBus.on('foo', function(event) {
- *
- *   // access event type
- *   event.type; // 'foo'
- *
- *   // stop propagation to other listeners
- *   event.stopPropagation();
- *
- *   // prevent event default
- *   event.preventDefault();
- * });
- *
- * // listen for event with custom payload
- * eventBus.on('bar', function(event, payload) {
- *   console.log(payload);
- * });
- *
- * // listen for event returning value
- * eventBus.on('foobar', function(event) {
- *
- *   // stop event propagation + prevent default
- *   return false;
- *
- *   // stop event propagation + return custom result
- *   return {
- *     complex: 'listening result'
- *   };
- * });
- *
- *
- * // listen with custom priority (default=1000, higher is better)
- * eventBus.on('priorityfoo', 1500, function(event) {
- *   console.log('invoked first!');
- * });
- *
- *
- * // listen for event and pass the context (`this`)
- * eventBus.on('foobar', function(event) {
- *   this.foo();
- * }, this);
- * ```
- *
- *
- * ## Emitting Events
- *
- * Events can be emitted via the event bus using {@link EventBus#fire}.
- *
- * ```javascript
- *
- * // false indicates that the default action
- * // was prevented by listeners
- * if (eventBus.fire('foo') === false) {
- *   console.log('default has been prevented!');
- * };
- *
- *
- * // custom args + return value listener
- * eventBus.on('sum', function(event, a, b) {
- *   return a + b;
- * });
- *
- * // you can pass custom arguments + retrieve result values.
- * var sum = eventBus.fire('sum', 1, 2);
- * console.log(sum); // 3
- * ```
- */
-
-function EventBus() {
-  this._listeners = {}; // cleanup on destroy on lowest priority to allow
-  // message passing until the bitter end
-
-  this.on('diagram.destroy', 1, this._destroy, this);
-}
-/**
- * Register an event listener for events with the given name.
- *
- * The callback will be invoked with `event, ...additionalArguments`
- * that have been passed to {@link EventBus#fire}.
- *
- * Returning false from a listener will prevent the events default action
- * (if any is specified). To stop an event from being processed further in
- * other listeners execute {@link Event#stopPropagation}.
- *
- * Returning anything but `undefined` from a listener will stop the listener propagation.
- *
- * @param {string|Array<string>} events
- * @param {number} [priority=1000] the priority in which this listener is called, larger is higher
- * @param {Function} callback
- * @param {Object} [that] Pass context (`this`) to the callback
- */
-
-EventBus.prototype.on = function (events, priority, callback, that) {
-  events = minDash.isArray(events) ? events : [events];
-
-  if (minDash.isFunction(priority)) {
-    that = callback;
-    callback = priority;
-    priority = DEFAULT_PRIORITY$1;
-  }
-
-  if (!minDash.isNumber(priority)) {
-    throw new Error('priority must be a number');
-  }
-
-  var actualCallback = callback;
-
-  if (that) {
-    actualCallback = minDash.bind(callback, that); // make sure we remember and are able to remove
-    // bound callbacks via {@link #off} using the original
-    // callback
-
-    actualCallback[FN_REF] = callback[FN_REF] || callback;
-  }
-
-  var self = this;
-  events.forEach(function (e) {
-    self._addListener(e, {
-      priority: priority,
-      callback: actualCallback,
-      next: null
-    });
-  });
-};
-/**
- * Register an event listener that is executed only once.
- *
- * @param {string} event the event name to register for
- * @param {number} [priority=1000] the priority in which this listener is called, larger is higher
- * @param {Function} callback the callback to execute
- * @param {Object} [that] Pass context (`this`) to the callback
- */
-
-
-EventBus.prototype.once = function (event, priority, callback, that) {
-  var self = this;
-
-  if (minDash.isFunction(priority)) {
-    that = callback;
-    callback = priority;
-    priority = DEFAULT_PRIORITY$1;
-  }
-
-  if (!minDash.isNumber(priority)) {
-    throw new Error('priority must be a number');
-  }
-
-  function wrappedCallback() {
-    wrappedCallback.__isTomb = true;
-    var result = callback.apply(that, arguments);
-    self.off(event, wrappedCallback);
-    return result;
-  } // make sure we remember and are able to remove
-  // bound callbacks via {@link #off} using the original
-  // callback
-
-
-  wrappedCallback[FN_REF] = callback;
-  this.on(event, priority, wrappedCallback);
-};
-/**
- * Removes event listeners by event and callback.
- *
- * If no callback is given, all listeners for a given event name are being removed.
- *
- * @param {string|Array<string>} events
- * @param {Function} [callback]
- */
-
-
-EventBus.prototype.off = function (events, callback) {
-  events = minDash.isArray(events) ? events : [events];
-  var self = this;
-  events.forEach(function (event) {
-    self._removeListener(event, callback);
-  });
-};
-/**
- * Create an EventBus event.
- *
- * @param {Object} data
- *
- * @return {Object} event, recognized by the eventBus
- */
-
-
-EventBus.prototype.createEvent = function (data) {
-  var event = new InternalEvent();
-  event.init(data);
-  return event;
-};
-/**
- * Fires a named event.
- *
- * @example
- *
- * // fire event by name
- * events.fire('foo');
- *
- * // fire event object with nested type
- * var event = { type: 'foo' };
- * events.fire(event);
- *
- * // fire event with explicit type
- * var event = { x: 10, y: 20 };
- * events.fire('element.moved', event);
- *
- * // pass additional arguments to the event
- * events.on('foo', function(event, bar) {
- *   alert(bar);
- * });
- *
- * events.fire({ type: 'foo' }, 'I am bar!');
- *
- * @param {string} [name] the optional event name
- * @param {Object} [event] the event object
- * @param {...Object} additional arguments to be passed to the callback functions
- *
- * @return {boolean} the events return value, if specified or false if the
- *                   default action was prevented by listeners
- */
-
-
-EventBus.prototype.fire = function (type, data) {
-  var event, firstListener, returnValue, args;
-  args = slice.call(arguments);
-
-  if (typeof type === 'object') {
-    data = type;
-    type = data.type;
-  }
-
-  if (!type) {
-    throw new Error('no event type specified');
-  }
-
-  firstListener = this._listeners[type];
-
-  if (!firstListener) {
-    return;
-  } // we make sure we fire instances of our home made
-  // events here. We wrap them only once, though
-
-
-  if (data instanceof InternalEvent) {
-    // we are fine, we alread have an event
-    event = data;
-  } else {
-    event = this.createEvent(data);
-  } // ensure we pass the event as the first parameter
-
-
-  args[0] = event; // original event type (in case we delegate)
-
-  var originalType = event.type; // update event type before delegation
-
-  if (type !== originalType) {
-    event.type = type;
-  }
-
-  try {
-    returnValue = this._invokeListeners(event, args, firstListener);
-  } finally {
-    // reset event type after delegation
-    if (type !== originalType) {
-      event.type = originalType;
-    }
-  } // set the return value to false if the event default
-  // got prevented and no other return value exists
-
-
-  if (returnValue === undefined && event.defaultPrevented) {
-    returnValue = false;
-  }
-
-  return returnValue;
-};
-
-EventBus.prototype.handleError = function (error) {
-  return this.fire('error', {
-    error: error
-  }) === false;
-};
-
-EventBus.prototype._destroy = function () {
-  this._listeners = {};
-};
-
-EventBus.prototype._invokeListeners = function (event, args, listener) {
-  var returnValue;
-
-  while (listener) {
-    // handle stopped propagation
-    if (event.cancelBubble) {
-      break;
-    }
-
-    returnValue = this._invokeListener(event, args, listener);
-    listener = listener.next;
-  }
-
-  return returnValue;
-};
-
-EventBus.prototype._invokeListener = function (event, args, listener) {
-  var returnValue;
-
-  if (listener.callback.__isTomb) {
-    return returnValue;
-  }
-
-  try {
-    // returning false prevents the default action
-    returnValue = invokeFunction(listener.callback, args); // stop propagation on return value
-
-    if (returnValue !== undefined) {
-      event.returnValue = returnValue;
-      event.stopPropagation();
-    } // prevent default on return false
-
-
-    if (returnValue === false) {
-      event.preventDefault();
-    }
-  } catch (error) {
-    if (!this.handleError(error)) {
-      console.error('unhandled error in event listener', error);
-      throw error;
-    }
-  }
-
-  return returnValue;
-};
-/*
- * Add new listener with a certain priority to the list
- * of listeners (for the given event).
- *
- * The semantics of listener registration / listener execution are
- * first register, first serve: New listeners will always be inserted
- * after existing listeners with the same priority.
- *
- * Example: Inserting two listeners with priority 1000 and 1300
- *
- *    * before: [ 1500, 1500, 1000, 1000 ]
- *    * after: [ 1500, 1500, (new=1300), 1000, 1000, (new=1000) ]
- *
- * @param {string} event
- * @param {Object} listener { priority, callback }
- */
-
-
-EventBus.prototype._addListener = function (event, newListener) {
-  var listener = this._getListeners(event),
-      previousListener; // no prior listeners
-
-
-  if (!listener) {
-    this._setListeners(event, newListener);
-
-    return;
-  } // ensure we order listeners by priority from
-  // 0 (high) to n > 0 (low)
-
-
-  while (listener) {
-    if (listener.priority < newListener.priority) {
-      newListener.next = listener;
-
-      if (previousListener) {
-        previousListener.next = newListener;
-      } else {
-        this._setListeners(event, newListener);
-      }
-
-      return;
-    }
-
-    previousListener = listener;
-    listener = listener.next;
-  } // add new listener to back
-
-
-  previousListener.next = newListener;
-};
-
-EventBus.prototype._getListeners = function (name) {
-  return this._listeners[name];
-};
-
-EventBus.prototype._setListeners = function (name, listener) {
-  this._listeners[name] = listener;
-};
-
-EventBus.prototype._removeListener = function (event, callback) {
-  var listener = this._getListeners(event),
-      nextListener,
-      previousListener,
-      listenerCallback;
-
-  if (!callback) {
-    // clear listeners
-    this._setListeners(event, null);
-
-    return;
-  }
-
-  while (listener) {
-    nextListener = listener.next;
-    listenerCallback = listener.callback;
-
-    if (listenerCallback === callback || listenerCallback[FN_REF] === callback) {
-      if (previousListener) {
-        previousListener.next = nextListener;
-      } else {
-        // new first listener
-        this._setListeners(event, nextListener);
-      }
-    }
-
-    previousListener = listener;
-    listener = nextListener;
-  }
-};
-/**
- * A event that is emitted via the event bus.
- */
-
-
-function InternalEvent() {}
-
-InternalEvent.prototype.stopPropagation = function () {
-  this.cancelBubble = true;
-};
-
-InternalEvent.prototype.preventDefault = function () {
-  this.defaultPrevented = true;
-};
-
-InternalEvent.prototype.init = function (data) {
-  minDash.assign(this, data || {});
-};
-/**
- * Invoke function. Be fast...
- *
- * @param {Function} fn
- * @param {Array<Object>} args
- *
- * @return {Any}
- */
-
-
-function invokeFunction(fn, args) {
-  return fn.apply(null, args);
-}
-
 /**
  * @typedef {Function} <propertiesPanel.showEntry> callback
  *
@@ -661,9 +188,8 @@ function invokeFunction(fn, args) {
  *
  * @returns void
  */
-const eventBus = new EventBus();
 const EventContext = preact.createContext({
-  eventBus
+  eventBus: null
 });
 
 const LayoutContext = preact.createContext({
@@ -684,7 +210,7 @@ const LayoutContext = preact.createContext({
  * ```
  *
  * @param {string} id
- * @param {djs.model.Base} element
+ * @param {object} element
  *
  * @returns {string}
  */
@@ -712,9 +238,13 @@ function useEvent(event, callback, priority = DEFAULT_PRIORITY) {
     eventBus
   } = hooks.useContext(EventContext);
   hooks.useEffect(() => {
+    if (!eventBus) {
+      return;
+    }
+
     eventBus.on(event, priority, callback);
     return () => eventBus.off(event, callback);
-  }, [event, eventBus, callback, priority]);
+  }, [callback, event, eventBus, priority]);
 }
 
 const HIGH_PRIORITY = 10000;
@@ -920,7 +450,10 @@ function useShowErrorEvent(show) {
     setTemporaryError(null);
 
     if (show(event)) {
-      eventBus.fire('propertiesPanel.showEntry', event);
+      if (eventBus) {
+        eventBus.fire('propertiesPanel.showEntry', event);
+      }
+
       setTemporaryError(event.message);
     }
   }, [show]);
@@ -928,6 +461,57 @@ function useShowErrorEvent(show) {
   return temporaryError;
 }
 
+/**
+ * @callback setSticky
+ * @param {boolean} value
+ */
+
+/**
+ * Use IntersectionObserver to identify when DOM element is in sticky mode.
+ * If sticky is observered setSticky(true) will be called.
+ * If sticky mode is left, setSticky(false) will be called.
+ *
+ *
+ * @param {Object} ref
+ * @param {string} scrollContainerSelector
+ * @param {setSticky} setSticky
+ */
+
+function useStickyIntersectionObserver(ref, scrollContainerSelector, setSticky) {
+  hooks.useEffect(() => {
+    // return early if IntersectionObserver is not available
+    if (!IntersectionObserver) {
+      return;
+    }
+
+    let observer;
+
+    if (ref.current) {
+      const scrollContainer = minDom.query(scrollContainerSelector);
+      observer = new IntersectionObserver(entries => {
+        if (entries[0].intersectionRatio < 1) {
+          setSticky(true);
+        } else if (entries[0].intersectionRatio === 1) {
+          setSticky(false);
+        }
+      }, {
+        root: scrollContainer,
+        rootMargin: '0px 0px 999999% 0px',
+        // Use bottom margin to avoid stickyness when scrolling out to bottom
+        threshold: [1]
+      });
+      observer.observe(ref.current);
+    } // Unobserve if unmounted
+
+
+    return () => {
+      if (ref.current && observer) {
+        observer.unobserve(ref.current);
+      }
+    };
+  }, [ref]);
+}
+
 function Group(props) {
   const {
     element,
@@ -936,12 +520,14 @@ function Group(props) {
     label,
     shouldOpen = false
   } = props;
+  const groupRef = hooks.useRef(null);
   const [open, setOpen] = useLayoutState(['groups', id, 'open'], shouldOpen);
   const onShow = hooks.useCallback(() => setOpen(true), [setOpen]);
 
   const toggleOpen = () => setOpen(!open);
 
-  const [edited, setEdited] = hooks.useState(false); // set edited state depending on all entries
+  const [edited, setEdited] = hooks.useState(false);
+  const [sticky, setSticky] = hooks.useState(false); // set edited state depending on all entries
 
   hooks.useEffect(() => {
     const hasOneEditedEntry = entries.find(entry => {
@@ -959,15 +545,18 @@ function Group(props) {
       return isEdited(inputNode);
     });
     setEdited(hasOneEditedEntry);
-  }, [entries]);
+  }, [entries]); // set css class when group is sticky to top
+
+  useStickyIntersectionObserver(groupRef, 'div.bio-properties-panel-scroll-container', setSticky);
   const propertiesPanelContext = { ...hooks.useContext(LayoutContext),
     onShow
   };
   return jsxRuntime.jsxs("div", {
     class: "bio-properties-panel-group",
     "data-group-id": 'group-' + id,
+    ref: groupRef,
     children: [jsxRuntime.jsxs("div", {
-      class: classnames__default["default"]('bio-properties-panel-group-header', edited ? '' : 'empty', open ? 'open' : ''),
+      class: classnames__default["default"]('bio-properties-panel-group-header', edited ? '' : 'empty', open ? 'open' : '', sticky && open ? 'sticky' : ''),
       onClick: toggleOpen,
       children: [jsxRuntime.jsx("div", {
         title: label,
@@ -1009,6 +598,33 @@ function DataMarker() {
   });
 }
 
+/**
+ * @typedef { {
+ *  text: (element: object) => string,
+ *  icon?: (element: Object) => import('preact').Component
+ * } } PlaceholderDefinition
+ *
+ * @param { PlaceholderDefinition } props
+ */
+function Placeholder(props) {
+  const {
+    text,
+    icon: Icon
+  } = props;
+  return jsxRuntime.jsx("div", {
+    class: "bio-properties-panel open",
+    children: jsxRuntime.jsxs("section", {
+      class: "bio-properties-panel-placeholder",
+      children: [Icon && jsxRuntime.jsx(Icon, {
+        class: "bio-properties-panel-placeholder-icon"
+      }), jsxRuntime.jsx("p", {
+        class: "bio-properties-panel-placeholder-text",
+        children: text
+      })]
+    })
+  });
+}
+
 const DEFAULT_LAYOUT = {
   open: true
 };
@@ -1055,10 +671,15 @@ const bufferedEvents = ['propertiesPanel.showEntry', 'propertiesPanel.showError'
  *
  * @callback { {
  * @param {string} id
- * @param {djs.model.base} element
+ * @param {Object} element
  * @returns {string}
  * } } GetDescriptionFunction
  *
+ * @typedef { {
+ *  getEmpty: (element: object) => import('./components/Placeholder').PlaceholderDefinition,
+ *  getMultiple: (element: Object) => import('./components/Placeholder').PlaceholderDefinition
+ * } } PlaceholderProvider
+ *
  */
 
 /**
@@ -1066,19 +687,22 @@ const bufferedEvents = ['propertiesPanel.showEntry', 'propertiesPanel.showError'
  * data from implementor to describe *what* will be rendered.
  *
  * @param {Object} props
- * @param {Object} props.element
+ * @param {Object|Array} props.element
  * @param {import('./components/Header').HeaderProvider} props.headerProvider
+ * @param {PlaceholderProvider} [props.placeholderProvider]
  * @param {Array<GroupDefinition|ListGroupDefinition>} props.groups
  * @param {Object} [props.layoutConfig]
  * @param {Function} [props.layoutChanged]
  * @param {DescriptionConfig} [props.descriptionConfig]
  * @param {Function} [props.descriptionLoaded]
+ * @param {Object} [props.eventBus]
  */
 
 function PropertiesPanel(props) {
   const {
     element,
     headerProvider,
+    placeholderProvider,
     groups,
     layoutConfig = {},
     layoutChanged,
@@ -1131,12 +755,16 @@ function PropertiesPanel(props) {
   };
   const propertiesPanelContext = {
     element
-  };
+  }; // empty state
 
-  if (!element) {
-    return jsxRuntime.jsx("div", {
-      class: "bio-properties-panel-placeholder",
-      children: "Select an element to edit its properties."
+  if (placeholderProvider && !element) {
+    return jsxRuntime.jsx(Placeholder, { ...placeholderProvider.getEmpty()
+    });
+  } // multiple state
+
+
+  if (placeholderProvider && minDash.isArray(element)) {
+    return jsxRuntime.jsx(Placeholder, { ...placeholderProvider.getMultiple()
     });
   }
 
@@ -1408,7 +1036,9 @@ function ListGroup(props) {
     shouldOpen = true,
     shouldSort = true
   } = props;
+  const groupRef = hooks.useRef(null);
   const [open, setOpen] = useLayoutState(['groups', id, 'open'], false);
+  const [sticky, setSticky] = hooks.useState(false);
   const onShow = hooks.useCallback(() => setOpen(true), [setOpen]);
   const [ordering, setOrdering] = hooks.useState([]);
   const [newItemAdded, setNewItemAdded] = hooks.useState(false);
@@ -1479,7 +1109,9 @@ function ListGroup(props) {
       });
       setOrdering(keep);
     }
-  }, [items, shouldHandleEffects]);
+  }, [items, shouldHandleEffects]); // set css class when group is sticky to top
+
+  useStickyIntersectionObserver(groupRef, 'div.bio-properties-panel-scroll-container', setSticky);
 
   const toggleOpen = () => setOpen(!open);
 
@@ -1490,8 +1122,9 @@ function ListGroup(props) {
   return jsxRuntime.jsxs("div", {
     class: "bio-properties-panel-group",
     "data-group-id": 'group-' + id,
+    ref: groupRef,
     children: [jsxRuntime.jsxs("div", {
-      class: classnames__default["default"]('bio-properties-panel-group-header', hasItems ? '' : 'empty', hasItems && open ? 'open' : ''),
+      class: classnames__default["default"]('bio-properties-panel-group-header', hasItems ? '' : 'empty', hasItems && open ? 'open' : '', sticky && open ? 'sticky' : ''),
       onClick: hasItems ? toggleOpen : noop$3,
       children: [jsxRuntime.jsx("div", {
         title: label,
@@ -2494,6 +2127,7 @@ exports.ListEntry = List;
 exports.ListGroup = ListGroup;
 exports.ListItem = ListItem;
 exports.NumberFieldEntry = NumberFieldEntry;
+exports.Placeholder = Placeholder;
 exports.PropertiesPanel = PropertiesPanel;
 exports.PropertiesPanelContext = LayoutContext;
 exports.SelectEntry = SelectEntry;
@@ -2516,4 +2150,5 @@ exports.useLayoutState = useLayoutState;
 exports.usePrevious = usePrevious;
 exports.useShowEntryEvent = useShowEntryEvent;
 exports.useShowErrorEvent = useShowErrorEvent;
+exports.useStickyIntersectionObserver = useStickyIntersectionObserver;
 //# sourceMappingURL=index.js.map