React Widget Dashboard Framework

Common errors

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause This typically occurs when a React component is imported incorrectly (e.g., trying to default import a named export, or using CommonJS `require` in an ESM context).
  fix Ensure all components are imported using named ES module syntax, like `import { ComponentName } from 'di-widgets-framework';`, and that your build setup supports ES Modules.

• TypeError: Cannot read properties of undefined (reading 'title') (or similar property of a widget object)

  cause A `Widget` object (or a nested property of it) expected by a component like `WidgetSettingsPanel` is `undefined` or `null`, often due to missing data or incorrect state management.
  fix Before rendering components that rely on complex objects, ensure the data (e.g., the `widget` prop) is valid and complete. Implement defensive coding with optional chaining (`?.`) or conditional rendering.

• Failed to load resource: the server responded with a status of 404 (Not Found) - for widgetBackendUrl API calls

  cause The backend API specified by `widgetBackendUrl` is inaccessible, the URL is incorrect, or the specific endpoint does not exist or is not configured correctly on the server.
  fix Verify the `widgetBackendUrl` value for typos and ensure your backend service is running and accessible at that exact URL. Confirm that the required API endpoints are correctly implemented and exposed.

Warnings

• gotcha Omitting the `widgetBackendUrl` prop for components like `WidgetPalette` and `WidgetSettingsPanel` defaults to relative API calls. This can lead to unexpected '404 Not Found' errors or network failures in non-root deployments or server-side rendering (SSR) environments.
  Fix: Always explicitly define `widgetBackendUrl` (e.g., `http://localhost:3001` or `/api`) for robust and predictable API routing, especially in production or complex deployment scenarios.
• gotcha The `WidgetSettingsPanel` component has critical required props: `pageId` (string) and `widget` (an object conforming to the `Widget` interface). Failure to provide valid values for these will result in runtime errors and prevent the panel from rendering or functioning correctly.
  Fix: Ensure that `pageId` is a non-empty string and `widget` is a valid object adhering to the `Widget` interface before attempting to render `WidgetSettingsPanel`.
• gotcha As a React framework, `di-widgets-framework` depends on `react` and `react-dom` as peer dependencies. Incompatible versions (e.g., using an older React with a newer framework, or vice-versa) can lead to runtime issues such as 'Invalid hook call' errors.
  Fix: Verify that your project's `react` and `react-dom` versions are compatible with the framework's requirements (typically React 17 or 18+). Run `npm install` or `yarn install` to ensure peer dependencies are correctly resolved.
• gotcha While the library ships with TypeScript types, incorrect usage or misconfiguration of your `tsconfig.json` can lead to type errors during compilation. For example, importing types as values (e.g., `import { Widget } from '...'`) rather than using `import type`.
  Fix: For types and interfaces, always use `import type { TypeName } from 'package-name';` to prevent accidental runtime imports and ensure proper type stripping during compilation. Review your `tsconfig.json` for strictness and module resolution settings.

Install

• npm install dp-widgets-framework npm
• yarn add dp-widgets-framework yarn
• pnpm add dp-widgets-framework pnpm

Imports

• WidgetPalette
  wrong:

  const WidgetPalette = require('di-widgets-framework').WidgetPalette;

  correct:

  import { WidgetPalette } from 'di-widgets-framework';

  The library uses named exports, primarily designed for ES Modules. CommonJS `require` syntax is not recommended and may lead to issues.
• WidgetSettingsPanel
  wrong:

  import WidgetSettingsPanel from 'di-widgets-framework/WidgetSettingsPanel';

  correct:

  import { WidgetSettingsPanel } from 'di-widgets-framework';

  Components are exported as named exports from the main package entry point, not as default exports or from sub-paths.
• Widget (Type)
  wrong:

  import { Widget } from 'di-widgets-framework';

  correct:

  import type { Widget } from 'di-widgets-framework';

  For TypeScript projects, it's best practice to use `import type` for interfaces and types to ensure they are stripped from the JavaScript output, avoiding accidental runtime imports.

Quickstart

This example demonstrates how to integrate `WidgetPalette` into a React application, showing a basic setup for a widget dashboard environment and highlighting the `widgetBackendUrl` prop.

import React from 'react';
import { WidgetPalette, WidgetDashboard } from 'di-widgets-framework';

function App() {
  // In a real application, you might fetch available widgets dynamically
  const availableWidgetTypes = [
    { id: 'search', name: 'Search Input', description: 'Search input widget' },
    { id: 'filter', name: 'Data Filter', description: 'Filter/facet widget' },
    { id: 'results', name: 'Results Display', description: 'Results display widget' },
    { id: 'analytics', name: 'Analytics Chart', description: 'Analytics/charts widget' },
  ];

  return (
    <div style={{ display: 'flex', height: '100vh', padding: '20px' }}>
      <div style={{ width: '25%', paddingRight: '20px', borderRight: '1px solid #eee' }}>
        <h3>Widget Palette</h3>
        <WidgetPalette 
          widgetBackendUrl="http://localhost:3001" 
          // In a real app, you might pass availableWidgetTypes as a prop if not fetched by backend
        />
      </div>
      <div style={{ flex: 1, paddingLeft: '20px' }}>
        <h3>Dashboard Area</h3>
        {/* WidgetDashboard component would be used here to render dropped widgets */}
        {/* Example: <WidgetDashboard backendUrl="http://localhost:3001" /> */}
        <p>Drag widgets from the palette onto this area.</p>
      </div>
    </div>
  );
}

export default App;