fix: update jsdocs for listbox

[streamside]

Motivation

Update JSDoc to improve API specification and typescript definitions. Changes:

• Add types for ListBox options containing fixed set of valid configs. For example, FrequencyMode and Direction.
• Use @interface to describe objects with a number of properties (instead of @typedef)

[T-Wizard]

I am OK with it but,
the change to @interface from @typedef should not be needed.
It is used a lot in picasso.js and if generating type from @typedef is broken we should look into it.

[streamside]

I am OK with it but, the change to @interface from @typedef should not be needed. It is used a lot in picasso.js and if generating type from @typedef is broken we should look into it.

I agree with you Tobias. When having another look at this Picasso.js uses scriptappy-from-jsdoc to create the API specification while Nebula.js uses @scriptappy/from-jsdoc. They handle @typedef differently and due to this the typescript defs becomes broken.

Long term I think we should use @scriptappy/from-jsdoc in all repos which means that this problem needs to be resolve in there or adapt @scriptappy/to-dts to support the format created by @scriptappy/from-jsdoc.

Example from Picasso.js (simplified):

  /**
   * @typedef {object} Registries
   * @property {registry} component Component registry
   * @property {registry} data Data registry
   * @property {registry} formatter Formatter registry
   * @property {registry} interaction Interaction registry
   * @property {registry} renderer Renderer registry
   * @property {registry} scale Scale registry
   */

  // API Specification
  {
    "Registries": {
      "kind": "object",
      "entries": {
        "component": {
          "description": "Component registry",
          "type": "#/definitions/registry"
        },
        "data": {
          "description": "Data registry",
          "type": "#/definitions/registry"
        },
        "formatter": {
          "description": "Formatter registry",
          "type": "#/definitions/registry"
        },
        ...
    }

Example from Nebula.js:

/**
 * @typedef {object} Segment
 * @property {string} segment The sub-string/segment cut out from the original label.
 * @property {boolean} highlighted A flag which tells whether the segment should be highlighted or not.
 */

// API Specification
{
    "Segment": {
      "kind": "alias",  // <-- object is wrapped in an alias
      "items": {
        "kind": "object",
        "entries": {
          "segment": {
            "description": "The sub-string/segment cut out from the original label.",
            "type": "string"
          },
          "highlighted": {
            "description": "A flag which tells whether the segment should be highlighted or not.",
            "type": "boolean"
          }
        }
      }
    }
}