add hybrid panel example

Author: imanjra

plugins/hello-world/package.json

@@ -2,7 +2,7 @@
     "name": "@voxel51/hello-world",
     "version": "1.0.0",
     "main": "src/HelloWorldPlugin.tsx",
-    "license": "MIT",
+    "license": "Apache 2.0",
     "fiftyone": {
         "script": "dist/index.umd.js"
     },

plugins/hybrid-panel/README.md

@@ -0,0 +1,345 @@
+# Hybrid Panel
+
+A hybrid panel is a design pattern in the FiftyOne plugins framework that
+enables you to build rich, highly interactive UI panels by combining both
+Python and JavaScript/React. This approach allows complex logic, data
+processing, and session integration to run in Python, while the frontend
+delivers a responsive, dynamic user experience—giving you the best of both
+worlds when creating advanced custom panels.
+
+## JavaScript (React)
+
+On the JavaScript side of a hybrid panel, you build the UI as a component
+plugin, implementing the React interface that defines how the panel looks and
+behaves. Once created, this component is registered so that the Python side can
+reference it as the panel’s view. In this layer, you render elements, read and
+update state, respond to user interactions, and consume data generated by
+Python events. The JavaScript side is responsible for delivering a smooth,
+interactive experience, while relying on Python for configuration and heavy
+backend logic.
+
+### Example
+
+```js
+import { PluginComponentType, registerComponent } from "@fiftyone/plugins";
+
+function MyCustomView(props) {
+    return <strong>MyCustomView</strong>;
+}
+
+registerComponent({
+    name: "MyCustomView", // Used in python example below
+    label: "MyCustomView",
+    component: MyCustomView,
+    type: PluginComponentType.Component,
+    activator: () => true,
+});
+```
+
+## Python
+
+The Python side of a hybrid panel handles all the foundational setup and
+backend logic. It registers the panel, defines its basic configuration (such as
+the label, icon, and where it appears in the interface), and initializes its
+state when the panel loads. Python also provides the panel’s event
+handlers—effectively the panel’s API—allowing the UI to trigger computations,
+retrieve data, and react to user interactions.
+
+### Example
+
+```py
+import fiftyone.operators as foo
+import fiftyone.operators.types as types
+
+class HybridPanel(foo.Panel):
+    @property
+    def config(self):
+        return foo.PanelConfig(
+            name="hybrid_panel",
+            label="Hybrid Panel",
+            icon="adjust",
+            surfaces="grid modal",
+        )
+
+    def on_load(self, ctx):
+        # on_load_logic...
+
+    def render(self, ctx):
+        panel = types.Object()
+        return types.Property(
+            panel,
+            view=types.View(component="MyCustomView", composite_view=True),
+        )
+
+def register(p):
+    p.register(HybridPanel)
+```
+
+## State vs Data
+
+Hybrid panels in FiftyOne support two forms of data storage: state and data.
+Although they work together, they serve very different purposes and should be
+used accordingly when building custom panels.
+
+A simple mental model:
+
+-   State = configuration
+-   Data = results derived from configuration
+
+In a typical hybrid panel lifecycle:
+
+-   A user updates state (e.g., selects a label field and score threshold).
+-   A Python callback reacts to that state change.
+-   The callback computes data (e.g., a filtered list of detections).
+-   The panel renders using both the lightweight state and the heavy data.
+
+### State: Small, Persistent Configuration
+
+State is the place to store lightweight configuration that represents the
+panel’s intent rather than its computed results. Think of state as:
+
+-   Small: simple values, flags, selected options, input parameters, panel
+    settings
+
+-   Persistent: survives page refreshes and browser reloads. In the open-source
+    app (OSS), state values stay in sync with the underlying Python session via
+    session.spaces.
+
+-   Synchronized: state is available to all panel events including on_load,
+    on_change_view, and any custom panel events you define.
+
+State should not store anything large. In most cases, it should only store what
+the user chooses or configures.
+
+Typical examples of state:
+
+-   Filters (label type, score threshold, tag selections)
+-   UI selections (checkboxes, dropdown values)
+-   Configuration options (which algorithm to run, which view field to inspect)
+-   State represents what the user wants.
+
+### Data: Large, Derived, and Computed Values
+
+Data is designed for storing heavy, computed, or dynamic results—anything that
+is too large or too volatile to live in state. Data values are not intended to
+be:
+
+-   Sent back and forth frequently between browser and Python
+-   Not persisted after a page reload
+-   Typically derived from state, acting as the output of computation or a
+    resolved value
+
+Data is typically used for large or expensive values such as:
+
+-   Precomputed arrays, lists, or mappings
+-   Computation outputs (e.g., results of running a model or applying a filter)
+-   Cached processed view information
+
+In most cases, data represents what the panel computes based on state.
+
+### Using state and data on Python side
+
+```py
+def increment(self, ctx):
+    # Note: there is no ctx.panel.get_data as only state is available in events
+    count = ctx.panel.get_state("count") or 0
+    count = count + 1
+    ctx.panel.set_state("count", count)
+    ctx.panel.set_data("double_count", count * 2)
+```
+
+### Using state and data on JavaScript side
+
+```js
+import { usePanelStatePartial } from "@fiftyone/spaces";
+
+function MyCustomView(props) {
+    // state + data is merged and is available in data prop
+    const { data } = props;
+
+    // Alternatively, the state can also be accessed and mutated using hook
+    const defaultState = {};
+    const localOnlyState = true;
+    // Note: setState will update the latest state sent for the next panel event
+    const stateKey = "state";
+    const [state, setState] = usePanelStatePartial(stateKey, defaultState);
+    // Note: setData updated will not be available to python side (local-only)
+    const dataKey = "data";
+    const [data, setData] = usePanelStatePartial(
+        dataKey,
+        defaultState,
+        localOnlyState
+    );
+}
+```
+
+### Avoid Using React.useState for Persistent Panel State
+
+In panels, including hybrid panels and custom components, any data stored in
+local `React.useState` is reset whenever the panel is moved, split, navigated
+away from, or when the entire app is reloaded in the browser. Because local
+state does not persist across these transitions, it’s recommended to use spaces
+state hooks (i,e `usePanelStatePartial`) for any values that need to remain
+stable and persistent.
+
+## Panel Events
+
+Panel events are the callbacks that drive a hybrid panel’s interactivity,
+allowing the frontend to communicate with Python whenever something meaningful
+happens. These events—such as on_load, on_change_view, or any custom events you
+define—act like the panel’s API, letting the UI trigger computations, update
+state, refresh data, or react to changes in the FiftyOne session. They provide
+the backbone of the panel’s logic flow, ensuring that user actions and
+application state stay in sync across Python and React.
+
+### Python: Defining amd providing panel event to custom view
+
+The Python side of a hybrid panel is where you define the panel’s event
+handlers. Events are functions that run in response to lifecycle events and
+user interactions. These events act as the panel’s backend logic layer,
+allowing you to initialize state, react to view changes, perform computations,
+and send results back to the UI. By defining these events in Python, you give
+your panel the ability to handle complex operations while keeping the frontend
+lightweight and responsive.
+
+#### Example
+
+```py
+
+def on_load(self, ctx):
+    count = ctx.panel.get_state("count") or 0
+    ctx.panel.set_state("count", count)
+
+def increment(self, ctx):
+    count = ctx.panel.get_state("count")
+    if count is None
+        ctx.panel.set_state("count", count)
+    else:
+        ctx.panel.set_state("count", count + 1)
+
+def set_double_count(self, ctx):
+    count = ctx.params("count")
+    ctx.panel.set_state("count", count)
+
+def render(self, ctx):
+    panel = types.Object()
+    return types.Property(
+        panel,
+        view=types.View(
+            component="MyCustomView",
+            composite_view=True,
+            increment=self.increment,
+            set_double_count=self.set_double_count
+        ),
+    )
+
+```
+
+### JS: Invoking panel events
+
+From your React components, you can trigger these events whenever the user
+interacts with the UI—such as clicking a button, changing a selection, or
+updating a filter. Invoking a panel event sends the relevant state or
+parameters to Python, executes the corresponding logic, and can return results
+or updates back to the frontend. This allows your JavaScript code to remain
+lightweight while leveraging Python for computation, data processing, and
+complex panel behavior.
+
+#### Example
+
+```js
+import {Stack, Button, Typography} from "@mui/material"
+
+function MyCustomView(props) {
+    const {data, schema} = props
+    const { increment, set_double_count } = schema.view
+    const { count } = data
+    const triggerPanelEvent = useTriggerPanelEvent();
+
+    const handleSetDoubleCountCallback = (response) => {
+        const {result, error} = response
+        console.log(result)
+        console.log(error)
+    }
+    const handleSetDoubleCount = () => {
+        const event = set_double_count
+        const params = {count}
+        const promptForInput = false // not applicable to panel events
+        triggerPanelEvent(
+            event,
+            params,
+            promptForInput,
+            handleSetDoubleCountCallback
+        );
+    }
+    const handleIncrement = () => {
+        const event = increment
+        triggerPanelEvent(event);
+    }
+
+    return (
+        <Stack direction="row" spacing={1}>
+            <Typography>{count}</Typography>
+            <Button onClick={() => {
+                handleIncrement()
+                handleSetDoubleCount()
+            }}>
+        </Stack>;
+    )
+}
+```
+
+## Database persistence using the ExecutionStore
+
+In Hybrid Panels, you can store and retrieve panel state or results in a
+persistent backend. The ExecutionStore provides a way to save panel outputs,
+configurations, or intermediate computations to the database, ensuring that
+important data is permanently persisted. By using the ExecutionStore, panels
+can maintain continuity, cache expensive computations, and provide a consistent
+experience across user sessions without relying solely on ephemeral frontend
+state.
+
+### Example
+
+```py
+
+def save_count(self, ctx):
+    store = ctx.store("hybrid_panel") # create or retrieve store for this panel
+    count = ctx.params("count")
+    store.set("saved_count", count)
+    ctx.ops.notify(
+        f"Saved count has been updated to: {count}",
+        variant="success",
+    )
+```
+
+## Caching using ExecutionCache
+
+Hybrid panels can temporarily store computed results for faster access and
+improved performance. The ExecutionCache allows panels to keep intermediate
+data in memory or database, reducing the need to recompute expensive operations
+each time the panel updates or the user interacts with the UI. By leveraging
+this cache, panels can deliver a more responsive experience while still relying
+on Python for heavy computations.
+
+### Example
+
+```py
+@execution_cache
+def get_fibonacci_number_cacheable(self, ctx):
+    n = ctx.params("count")
+    return get_fibonacci_number(n)
+```
+
+## More examples
+
+### Model Evaluation Panel
+
+#### Python
+
+-   https://github.com/voxel51/fiftyone/tree/develop/plugins/panels/model_evaluation
+-   https://github.com/voxel51/fiftyone/tree/develop/plugins/operators/model_evaluation
+
+#### JavaScript
+
+-   https://github.com/voxel51/fiftyone/tree/develop/app/packages/core/src/plugins/SchemaIO/components/NativeModelEvaluationView