[storybook] Refines StoryBook site

This commit breaks a lot of stories permalinks. They are supposed to be
fixed within sigma.js resources, but might break somewhere else.

Details:
- Upgrades all StoryBook dependencies
- Adds simple documentation homepage as a story
- Reorganizes all stories
- Moves onStoryDown outside the stories, to get less noise in the
  visible stories codesources
- Refines settings, to hide toolbar, only show the "Code" addon, and get
  it more readable by default
- Cleans a lot of unused addons and settings
- Fixes all StoryBook permalinks from READMEs and documentation website

packages/edge-curve/README.md

@@ -15,7 +15,7 @@ It also exports:
 - `EdgeCurvedArrowProgram`, a program with defaults settings adapted to render edges as curved arrows
 - `createEdgeCurveProgram`, the factory to build a `CustomEdgeCurveProgram` with customized settings
 - `DEFAULT_EDGE_CURVATURE`, the default curvature value for edges
-- `indexParallelEdgesIndex`, a utility function to find parallel edges, and help adapt their `curvature` for display (see the [dedicated example](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/edge-curve/parallel-edges.ts) to see how it works)
+- `indexParallelEdgesIndex`, a utility function to find parallel edges, and help adapt their `curvature` for display (see the [dedicated example](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/edge-curve/parallel-edges.ts) to see how it works)
 
 ## How to use
 
@@ -36,4 +36,4 @@ const sigma = new Sigma(graph, container, {
 });
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/edge-curve) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/edge-curve) for more advanced examples.

packages/layer-leaflet/README.md

@@ -24,4 +24,4 @@ const sigma = new Sigma(graph, container);
 bindLeafletLayer(sigma);
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/layer-leaflet) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/layer-leaflet) for more advanced examples.

packages/layer-maplibre/README.md

@@ -24,4 +24,4 @@ const sigma = new Sigma(graph, container);
 bindMaplibreLayer(sigma);
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/layer-maplibre) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/layer-maplibre) for more advanced examples.

packages/layer-webgl/README.md

@@ -37,4 +37,4 @@ const renderer = new Sigma(graph, container);
 bindWebGLLayer("metaballs", renderer, createContoursProgram(graph.nodes()));
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/layer-webgl) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/layer-webgl) for more advanced examples.

packages/node-border/README.md

@@ -38,4 +38,4 @@ const sigma = new Sigma(graph, container, {
 });
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/node-border) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/node-border) for more advanced examples.

packages/node-image/README.md

@@ -33,7 +33,7 @@ const sigma = new Sigma(graph, container, {
 });
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/node-image) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/node-image) for more advanced examples.
 
 ## Factory options
 

packages/node-piechart/README.md

@@ -39,4 +39,4 @@ const sigma = new Sigma(graph, container, {
 });
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/node-piechart) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/node-piechart) for more advanced examples.

packages/node-square/README.md

@@ -26,4 +26,4 @@ const sigma = new Sigma(graph, container, {
 });
 ```
 
-Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/node-square) for more advanced examples.
+Please check the related [Storybook](https://github.com/jacomyal/sigma.js/tree/main/packages/storybook/stories/3-additional-packages/node-square) for more advanced examples.

packages/storybook/.storybook/main.ts

@@ -4,20 +4,15 @@ import { mergeConfig } from "vite";
 
 /** @type { import('@storybook/html-vite').StorybookConfig } */
 const config: StorybookConfig = {
-  stories: ["../stories/**/stories.ts", "../../**/src/**/*.mdx", "../../**/src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  stories: ["../stories/**/*.mdx", "../stories/**/stories.ts"],
   addons: [
-    getAbsolutePath("@storybook/addon-links"),
-    getAbsolutePath("@storybook/addon-essentials"),
-    getAbsolutePath("@storybook/addon-interactions"),
+    { name: "@storybook/addon-essentials", options: { actions: false, controls: false } },
     getAbsolutePath("@storybook/addon-storysource"),
   ],
   framework: getAbsolutePath("@storybook/html-vite"),
   typescript: {
     check: true,
   },
-  docs: {
-    autodocs: "tag",
-  },
   core: {
     disableTelemetry: true,
   },

packages/storybook/.storybook/manager.tsx

@@ -8,4 +8,12 @@ document.body.append(image);
 
 addons.setConfig({
   theme,
+  showToolbar: false,
+  panelPosition: "bottom",
+  bottomPanelHeight: 380,
+  sidebar: {
+    renderLabel(item) {
+      return item.name.replace(/--/g, "/");
+    },
+  },
 });

packages/storybook/.storybook/preview.tsx

@@ -27,15 +27,6 @@ const forceReloadDecorator: Preview["decorators"] = (storyFn, context) => {
 
 const preview: Preview = {
   decorators: [forceReloadDecorator],
-  parameters: {
-    actions: { argTypesRegex: "^on[A-Z].*" },
-    controls: {
-      matchers: {
-        color: /(background|color)$/i,
-        date: /Date$/i,
-      },
-    },
-  },
 };
 
 export default preview;

packages/storybook/.storybook/theme.ts

@@ -1,4 +1,4 @@
-import { create } from "@storybook/theming/create";
+import { create } from "@storybook/theming";
 
 export default create({
   base: "light",

packages/storybook/package.json

@@ -23,14 +23,14 @@
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@storybook/addon-essentials": "^8.0.0",
-    "@storybook/addon-interactions": "^8.0.0",
-    "@storybook/addon-links": "^8.0.0",
-    "@storybook/addon-storysource": "^8.0.0",
-    "@storybook/html": "^8.0.0",
-    "@storybook/html-vite": "^8.0.0",
-    "@storybook/web-components": "^8.0.0",
-    "storybook": "^8.0.0"
+    "@storybook/addon-essentials": "^8.3.3",
+    "@storybook/addon-storysource": "^8.3.3",
+    "@storybook/html": "^8.3.3",
+    "@storybook/html-vite": "^8.3.3",
+    "@storybook/manager-api": "^8.3.3",
+    "@storybook/theming": "^8.3.3",
+    "@storybook/web-components": "^8.3.3",
+    "storybook": "^8.3.3"
   },
   "scripts": {
     "start": "storybook dev -p 6006",

packages/storybook/stories/0-docs/introduction.mdx

@@ -0,0 +1,37 @@
+import { Meta } from "@storybook/addon-docs";
+
+<Meta title="Introduction" />
+
+![Sigma.js](https://raw.githubusercontent.com/jacomyal/sigma.js/main/packages/website/static/img/logo-sigma-text.png)
+
+**[Website](https://www.sigmajs.org/)** | **[Documentation](https://www.sigmajs.org/docs)** | **[GitHub](https://github.com/jacomyal/sigma.js)** | <strong><a rel="me" href="https://vis.social/@sigmajs">Mastodon</a></strong>
+
+---
+
+This Storybook is designed to help you explore the different features and use cases of sigma.js by showcasing various scenarios. Each story displays the full source code below, allowing you to easily reference and implement these examples in your own projects.
+
+## Core Library
+
+### Features showcases
+
+This section showcases basic scenarios that demonstrate the fundamental features of sigma.js. If you're just getting started, this is a great place to explore and understand the core functionalities.
+
+### Advanced Use Cases
+
+For more advanced use cases, this section delves deeper into sigma.js capabilities. Here, you'll find stories that highlight more complex scenarios and techniques, ideal for experienced users looking to extend sigma.js further.
+
+## Satellite Packages
+
+There are multiple features of sigma.js that are exposed from additional packages. The list of these packages is available [on NPM](https://www.npmjs.com/org/sigma). This section presents stories specific to these additional packages.
+
+---
+
+## Getting Started
+
+You can use the sidebar to navigate the stories.
+
+And if you don't know where to start, here are some cherry-picked entry points:
+
+- [I come from Gephi and I want to display my GEXF graph](./?path=/story/load-gexf-file--story)
+- [I have some CSV data and I want to render a network of connections from that file](./?path=/story/csv-to-network-map--story)
+- [I have some geo-localized network dataset and I want to render it hover a map background](./?path=/story/sigma-layer-maplibre--story)

packages/storybook/stories/load-gexf-file/index.ts → packages/storybook/stories/1-core-features/1-load-gexf-file/index.ts

@@ -8,8 +8,6 @@ import Graph from "graphology";
 import { parse } from "graphology-gexf/browser";
 import Sigma from "sigma";
 
-import { onStoryDown } from "../utils";
-
 export default () => {
   let renderer: Sigma | null = null;
 
@@ -27,10 +25,10 @@ export default () => {
       const zoomResetBtn = document.getElementById("zoom-reset") as HTMLButtonElement;
       const labelsThresholdRange = document.getElementById("labels-threshold") as HTMLInputElement;
 
-      // Instanciate sigma:
+      // Instantiate sigma:
       renderer = new Sigma(graph, container, {
-        minCameraRatio: 0.1,
-        maxCameraRatio: 10,
+        minCameraRatio: 0.08,
+        maxCameraRatio: 3,
       });
       const camera = renderer.getCamera();
 
@@ -54,7 +52,7 @@ export default () => {
       labelsThresholdRange.value = renderer.getSetting("labelRenderedSizeThreshold") + "";
     });
 
-  onStoryDown(() => {
+  return () => {
     renderer?.kill();
-  });
+  };
 };

packages/storybook/stories/load-gexf-file/stories.ts → packages/storybook/stories/1-core-features/1-load-gexf-file/stories.ts

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/web-components";
 
+import { wrapStory } from "../../utils";
 import play from "./index";
 import template from "./index.html?raw";
 import source from "./index?raw";
 
 const meta: Meta = {
   id: "load-gexf-file",
-  title: "Examples",
+  title: "Core library/Features showcases",
 };
 export default meta;
 
@@ -15,7 +16,7 @@ type Story = StoryObj;
 export const story: Story = {
   name: "Load GEXF file",
   render: () => template,
-  play,
+  play: wrapStory(play),
   args: {},
   parameters: {
     storySource: {

packages/storybook/stories/events/index.ts → packages/storybook/stories/1-core-features/2-events/index.ts

@@ -5,8 +5,7 @@ import Graph from "graphology";
 import Sigma from "sigma";
 import { MouseCoords } from "sigma/types";
 
-import data from "../_data/data.json";
-import { onStoryDown } from "../utils";
+import data from "../../_data/data.json";
 
 export default () => {
   const container = document.getElementById("sigma-container") as HTMLElement;
@@ -84,7 +83,7 @@ export default () => {
     });
   });
 
-  onStoryDown(() => {
+  return () => {
     renderer.kill();
-  });
+  };
 };

packages/storybook/stories/events/stories.ts → packages/storybook/stories/1-core-features/2-events/stories.ts

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/web-components";
 
+import { wrapStory } from "../../utils";
 import play from "./index";
 import template from "./index.html?raw";
 import source from "./index?raw";
 
 const meta: Meta = {
   id: "events",
-  title: "Examples",
+  title: "Core library/Features showcases",
 };
 export default meta;
 
@@ -15,7 +16,7 @@ type Story = StoryObj;
 export const story: Story = {
   name: "Events",
   render: () => template,
-  play,
+  play: wrapStory(play),
   args: {},
   parameters: {
     storySource: {

packages/storybook/stories/layouts/index.ts → packages/storybook/stories/1-core-features/3-layouts/index.ts

@@ -10,8 +10,7 @@ import Sigma from "sigma";
 import { PlainObject } from "sigma/types";
 import { animateNodes } from "sigma/utils";
 
-import data from "../_data/data.json";
-import { onStoryDown } from "../utils";
+import data from "../../_data/data.json";
 
 export default () => {
   // Initialize the graph object with data
@@ -119,7 +118,7 @@ export default () => {
   /** instantiate sigma into the container **/
   const renderer = new Sigma(graph, container);
 
-  onStoryDown(() => {
+  return () => {
     renderer.kill();
-  });
+  };
 };

packages/storybook/stories/layouts/stories.ts → packages/storybook/stories/1-core-features/3-layouts/stories.ts

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/web-components";
 
+import { wrapStory } from "../../utils";
 import play from "./index";
 import template from "./index.html?raw";
 import source from "./index?raw";
 
 const meta: Meta = {
   id: "layouts",
-  title: "Examples",
+  title: "Core library/Features showcases",
 };
 export default meta;
 
@@ -15,7 +16,7 @@ type Story = StoryObj;
 export const story: Story = {
   name: "Layouts example",
   render: () => template,
-  play,
+  play: wrapStory(play),
   args: {},
   parameters: {
     storySource: {

packages/storybook/stories/use-reducers/index.ts → packages/storybook/stories/1-core-features/4-use-reducers/index.ts

@@ -7,8 +7,7 @@ import Graph from "graphology";
 import Sigma from "sigma";
 import { Coordinates, EdgeDisplayData, NodeDisplayData } from "sigma/types";
 
-import data from "../_data/data.json";
-import { onStoryDown } from "../utils";
+import data from "../../_data/data.json";
 
 export default () => {
   // Retrieve some useful DOM elements:
@@ -178,7 +177,7 @@ export default () => {
     return res;
   });
 
-  onStoryDown(() => {
+  return () => {
     renderer.kill();
-  });
+  };
 };

packages/storybook/stories/use-reducers/stories.ts → packages/storybook/stories/1-core-features/4-use-reducers/stories.ts

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/web-components";
 
+import { wrapStory } from "../../utils";
 import play from "./index";
 import template from "./index.html?raw";
 import source from "./index?raw";
 
 const meta: Meta = {
   id: "use-reducers",
-  title: "Examples",
+  title: "Core library/Features showcases",
 };
 export default meta;
 
@@ -15,7 +16,7 @@ type Story = StoryObj;
 export const story: Story = {
   name: "Use node and edge reducers",
   render: () => template,
-  play,
+  play: wrapStory(play),
   args: {},
   parameters: {
     storySource: {

packages/storybook/stories/custom-rendering/index.ts → packages/storybook/stories/1-core-features/5-custom-rendering/index.ts

@@ -27,7 +27,6 @@ import Graph from "graphology";
 import ForceSupervisor from "graphology-layout-force/worker";
 import Sigma from "sigma";
 
-import { onStoryDown } from "../utils";
 import NodeGradientProgram from "./node-gradient";
 
 export default () => {
@@ -76,8 +75,8 @@ export default () => {
   const layout = new ForceSupervisor(graph);
   layout.start();
 
-  onStoryDown(() => {
+  return () => {
     layout.kill();
     renderer.kill();
-  });
+  };
 };