feat: full screen (#180)

* feat: add fullscreen support

This PR also implements #38

* fix: typo

* fix: properly alpha blend when saving a view as PNG

* fix: allow exporting an upscaled image

* docs: fix docstring of `scatter.show()`

* fix: ensure inputs and select adhere to Jupyter Widgets styles

* docs: describe advanced exporting

* docs: document `scatter.show()`

* chore: update vitepress

* fix: pass `buttons` on to `scatter.widget.show()`

* test: fix camera fixed test

* docs: mention full-screen mode addition

CHANGELOG.md

@@ -1,8 +1,10 @@
 ## v0.20.0
 
+- Feat: add support for showing a scatter plot in full-screen mode. In full-screen mode you can easily customize and up-scale the resolution for better exporting in PNG.
 - Feat: add ability to change the point size zoom scale function via `scatter.size(scale_function='asinh')`
 - Feat: add `scatter.camera(is_fixed=True)` to allow fixing the camera (i.e., disable pan/zoom) [#176](https://github.com/flekschas/jupyter-scatter/issues/176)
 - Feat: add CLI for quick-starting a demo via `uvx jupyter-scatter demo`
+- Fix: properly alpha blend when saving a view as PNG
 - Chore: switch from ESLint+Prettier to Biome [#170](https://github.com/flekschas/jupyter-scatter/pull/170)
 - Chore: migrate from hatch to uv [#169](https://github.com/flekschas/jupyter-scatter/pull/169)
 - Chore: bump minimum Python version to 3.9

docs/api.md

@@ -42,6 +42,32 @@ scatter.show()
 
 ## Methods {#methods}
 
+### scatter.show(_buttons=Undefined_) {#scatter.show}
+
+Show the scatter plot widget.
+
+**Arguments:**
+- `buttons`: The buttons to show in the widget. Can be one of the following:
+  - `"pan_zoom"`: Button to activate the pan and zoom mode.
+  - `"lasso"`: Button to activate the lasso mode.
+  - `"full_screen"`: Button to enter full screen mode.
+  - `"save"`: Button to save the current view in `scatter.widget.view_data`.
+  - `"download"`: Button to download the current view as a PNG image.
+  - `"reset"`: Button to reset the view.
+  - `"divider"`: Not a button, but a divider between buttons.
+
+**Returns:** either the x coordinate when x is `Undefined` or `self`.
+
+**Examples:**
+
+```python
+# Show the widget with all buttons
+scatter.show()
+
+# Show the widget with only a subset of buttons
+scatter.show(['full_screen', 'download', 'reset'])
+```
+
 ### scatter.x(_x=Undefined_, _scale=Undefined_, _\*\*kwargs_) {#scatter.x}
 
 Get or set the x coordinate.

docs/export-image.md

@@ -7,7 +7,8 @@ it as a PNG or save it to the widget's `view_data` property.
 Image exports follow [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG), meaning
 that the exported image will have the exact same size and viewport as the
 widget. Hence, if you want to export a higher resolution image you have to
-increase the scatter's width and height.
+increase the scatter's width and height. See [custom PNG export](#customize-png-export)
+on how to easily adjust the export resolution.
 :::
 
 ## Export as PNG
@@ -40,6 +41,22 @@ a transparent background by holding down <kbd>Alt</kbd> while clicking on the
 camera button.
 :::
 
+### Customize PNG Export
+
+To better control the resolution of the exported PNG, enter the full-screen mode
+(via the widget button on the left) and open up the resize panel (via the up
+arrow button in the bottom-left corner). This panel allows you to easily
+customize the width/height of the scatter plot and offers the ability to
+up-scale the exported image.
+
+<div class="img export-download-png-advanced"><div /></div>
+
+::: info
+Note, the exported image is subject to your [device pixel ratio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio), which cannot be changed. This means that if your plot is 
+100 by 100 pixels in size and your display has a pixel ratio of `2`, the
+exported PNG is going to be 200 by 200 pixels.
+:::
+
 ## Export to `widget.view_data`
 
 When you click on the camera icon, the current view will be exported and saved
@@ -101,6 +118,16 @@ plt.show()
     background-image: url(/images/export-download-png-dark.png)
   }
 
+  .img.export-download-png-advanced {
+    width: 3024px;
+    background-image: url(/images/full-screen-light.png)
+  }
+  .img.export-download-png-advanced div { padding-top: 62.5% }
+
+  :root.dark .img.export-download-png-advanced {
+    background-image: url(/images/full-screen-dark.png)
+  }
+
   .img.export-save {
     width: 1108px;
     background-image: url(/images/export-save-light.png)