feat: widget vibe gallery migration

docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_cli_examples.md

@@ -0,0 +1,21 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/progress/bec_progressbar/bec_progressbar.py
+- Public example surface: USER_ACCESS includes set_value, set_maximum, set_minimum, label_template setter, state setter, _get_label. set_value(value), set_maximum(maximum: float), set_minimum(minimum: float).
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.BECProgressBar).
+-->
+
+Create and update a progress bar:
+
+```python
+progress = gui.bec.new(gui.available_widgets.BECProgressBar)
+progress.set_minimum(0)
+progress.set_maximum(100)
+progress.set_value(25)
+```
+
+Customize the displayed label:
+
+```python
+progress.label_template = "$value / $maximum ($percentage %)"
+```

docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_description.md

@@ -0,0 +1,3 @@
+BECProgressBar is a linear progress indicator with a configurable label template. Use it for custom progress feedback in utility layouts.
+
+![BECProgressBar widget](assets/bec_progressbar.png)

docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_page.md

@@ -0,0 +1,22 @@
+# BECProgressBar
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.progress.bec_progressbar.bec_progressbar.BECProgressBar
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///

docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_cli_examples.md

@@ -0,0 +1,22 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/services/bec_queue/bec_queue.py
+- Public example surface: BECQueue is PLUGIN=True. It does not define widget-specific USER_ACCESS; examples are limited to creation and base attach/detach behavior.
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.BECQueue).
+-->
+
+Create the queue widget:
+
+```python
+queue = gui.bec.new(gui.available_widgets.BECQueue)
+```
+
+Place it next to a ScanControl widget:
+
+```python
+queue = gui.bec.new(
+    gui.available_widgets.BECQueue,
+    where="right",
+    relative_to="ScanControl",
+)
+```

docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_description.md

@@ -0,0 +1,3 @@
+BECQueue displays the scan queue and queue control buttons. Use it when an operator needs queue status visible in the Dock Area.
+
+![BECQueue widget](assets/queue.png)

docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_page.md

@@ -0,0 +1,22 @@
+# BECQueue
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/bec_queue/bec_queue_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/bec_queue/bec_queue_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.services.bec_queue.bec_queue.BECQueue
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///

docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_cli_examples.md

@@ -0,0 +1,18 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/services/bec_status_box/bec_status_box.py
+- Public example surface: USER_ACCESS includes get_server_state, remove, attach, detach, screenshot. get_server_state(self) -> str.
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.BECStatusBox).
+-->
+
+Create a status box:
+
+```python
+status = gui.bec.new(gui.available_widgets.BECStatusBox)
+```
+
+Read the current top-level server state:
+
+```python
+state = status.get_server_state()
+```

docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_description.md

@@ -0,0 +1,3 @@
+BECStatusBox displays the status of core BEC services. Use it in operational layouts where service health should be visible at a glance.
+
+![BECStatusBox widget](assets/status_box.png)

docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_page.md

@@ -0,0 +1,22 @@
+# BECStatusBox
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.services.bec_status_box.bec_status_box.BECStatusBox
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///

docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_cli_examples.md

@@ -0,0 +1,17 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/dap/dap_combo_box/dap_combo_box.py
+- Public example surface: USER_ACCESS includes select_y_axis, select_x_axis, select_fit_model. select_fit_model validates against available DAP models and raises ValueError for invalid names.
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.DapComboBox).
+-->
+
+Create a DapComboBox and select axes/model:
+
+```python
+dap = gui.bec.new(gui.available_widgets.DapComboBox)
+dap.select_x_axis("samx")
+dap.select_y_axis("bpm4i")
+dap.select_fit_model("GaussianModel")
+```
+
+The model name must be available in the current DAP service. Invalid model names raise an error.

docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_description.md

@@ -0,0 +1,3 @@
+DapComboBox lists available DAP models and can emit a DAP configuration when x-axis, y-axis, and model are selected. Most users interact with DAP through Waveform, but this widget is useful in custom GUI compositions.
+
+![DapComboBox widget](assets/dap_combo_box.png)

docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_page.md

@@ -0,0 +1,22 @@
+# DapComboBox
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.dap.dap_combo_box.dap_combo_box.DapComboBox
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///

docs/references/bec-widgets/widget-gallery/device_browser/device_browser_cli_examples.md

@@ -0,0 +1,22 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/services/device_browser/device_browser.py
+- Public example surface: DeviceBrowser is PLUGIN=True with ICON_NAME="lists" and no widget-specific USER_ACCESS list; only base BECWidget operations should be shown from CLI.
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.DeviceBrowser).
+-->
+
+Create a DeviceBrowser widget:
+
+```python
+devices = gui.bec.new(gui.available_widgets.DeviceBrowser)
+```
+
+Place it beside the current Waveform:
+
+```python
+devices = gui.bec.new(
+    gui.available_widgets.DeviceBrowser,
+    where="right",
+    relative_to="Waveform",
+)
+```

docs/references/bec-widgets/widget-gallery/device_browser/device_browser_description.md

@@ -0,0 +1,5 @@
+DeviceBrowser shows the devices available in the current BEC session. Use it to inspect configured devices and browse their metadata from the GUI.
+
+![DeviceBrowser widget](assets/device_browser.png)
+
+The useful interactions are GUI-based; from the BEC IPython client, create it in the Dock Area and then interact with the displayed device list.

docs/references/bec-widgets/widget-gallery/device_browser/device_browser_page.md

@@ -0,0 +1,22 @@
+# DeviceBrowser
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/device_browser/device_browser_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/device_browser/device_browser_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.services.device_browser.device_browser.DeviceBrowser
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///

docs/references/bec-widgets/widget-gallery/heatmap/heatmap_cli_examples.md

@@ -0,0 +1,39 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/plots/heatmap/heatmap.py
+- Public example surface: USER_ACCESS includes plot, color_map, v_min/v_max, interpolation_method, oversampling_factor, enforce_interpolation, fft, log, device/signal properties; plot(device_x, device_y, device_z, signal_x=None, signal_y=None, signal_z=None, color_map="plasma", validate_bec=True, interpolation=None, enforce_interpolation=None, oversampling_factor=None, lock_aspect_ratio=None, show_config_label=None, reload=False).
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.Heatmap).
+-->
+
+Create a Heatmap for `samx`, `samy`, and `bpm4i`:
+
+```python
+heatmap = gui.bec.new(gui.available_widgets.Heatmap)
+heatmap.plot(
+    device_x="samx",
+    device_y="samy",
+    device_z="bpm4i",
+    color_map="plasma",
+)
+```
+
+Adjust interpolation and display settings:
+
+```python
+heatmap.interpolation_method = "nearest"
+heatmap.oversampling_factor = 2.0
+heatmap.enable_full_colorbar = True
+```
+
+Reload with explicit plotting options:
+
+```python
+heatmap.plot(
+    device_x="samx",
+    device_y="samy",
+    device_z="bpm4i",
+    interpolation="linear",
+    oversampling_factor=1.5,
+    reload=True,
+)
+```

docs/references/bec-widgets/widget-gallery/heatmap/heatmap_description.md

@@ -0,0 +1,9 @@
+Heatmap displays 2D scan data using a color-mapped image. It is the right choice for grid scans and for step scans that should be interpolated onto a 2D surface.
+
+![Heatmap widget](assets/heatmap_widget.png)
+
+Common uses:
+
+- plot `x`, `y`, and detector intensity from grid scans
+- interpolate irregular step-scan points
+- tune oversampling, interpolation, and color maps

docs/references/bec-widgets/widget-gallery/heatmap/heatmap_page.md

@@ -0,0 +1,22 @@
+# Heatmap
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/heatmap/heatmap_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/heatmap/heatmap_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.plots.heatmap.heatmap.Heatmap
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///

docs/references/bec-widgets/widget-gallery/image/image_cli_examples.md

@@ -0,0 +1,29 @@
+<!--
+Source verification audit:
+- Source checked: /Users/janwyzula/PSI/bec_widgets/bec_widgets/widgets/plots/image/image.py and bec_widgets/widgets/plots/image/image_base.py
+- Public example surface: Image USER_ACCESS includes device/device.setter, signal/signal.setter, color_map, v_min/v_max, colorbar flags, fft, log, num_rotation_90, transpose, main_image, add_roi, remove_roi, rois. ImageBase exposes add_roi/remove_roi used by Image.
+- Examples use V3 Dock Area creation through gui.bec.new(gui.available_widgets.Image).
+-->
+
+Create an Image widget and connect it to a detector signal. Replace `camera` and `image` with the device and signal names used at your beamline:
+
+```python
+img = gui.bec.new(gui.available_widgets.Image)
+img.device = "camera"
+img.signal = "image"
+```
+
+Adjust the display:
+
+```python
+img.color_map = "viridis"
+img.enable_full_colorbar = True
+img.log = True
+```
+
+Add and remove an ROI:
+
+```python
+img.add_roi(name="beam_roi")
+img.remove_roi("beam_roi")
+```

docs/references/bec-widgets/widget-gallery/image/image_description.md

@@ -0,0 +1,10 @@
+Image displays 2D data from detector signals. Use it for cameras, area detectors, and other image-like data streams that should be inspected as an image rather than as a curve.
+
+![Image widget](assets/image_widget.png)
+
+Common uses:
+
+- display live 2D detector output
+- adjust color map and color range
+- apply log or FFT display transformations
+- create image ROIs for inspection

docs/references/bec-widgets/widget-gallery/image/image_page.md

@@ -0,0 +1,22 @@
+# Image
+
+/// tab | Description
+
+--8<-- "references/bec-widgets/widget-gallery/image/image_description.md"
+
+///
+/// tab | BEC IPython examples
+
+--8<-- "references/bec-widgets/widget-gallery/image/image_cli_examples.md"
+
+///
+/// tab | API
+
+::: bec_widgets.widgets.plots.image.image.Image
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+
+
+///