Merge pull request #4 from source-academy/dev

[0.0.4] Add Storybook for documentation

.gitignore

@@ -1 +1,3 @@
 node_modules
+
+*storybook.log

.storybook/main.ts

@@ -0,0 +1,27 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+  stories: ["./stories/**/*.mdx", "./stories/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  addons: [
+    // "@storybook/addon-onboarding",
+    // "@storybook/addon-links",
+    // "@storybook/addon-essentials",
+    // "@chromatic-com/storybook",
+    // "@storybook/addon-interactions",
+    {
+      name: "@storybook/addon-essentials",
+      options: {
+        actions: false,
+      },
+    }
+  ],
+  framework: {
+    name: "@storybook/react-vite",
+    options: {},
+  },
+  docs: {
+    autodocs: "tag",
+  },
+
+};
+export default config;

.storybook/preview.ts

@@ -0,0 +1,18 @@
+import type { Preview } from "@storybook/react";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    }, options: {
+      storySort: {
+        order: ['Getting started', ['nbody', 'Installation', 'Integration'], 'Usage', 'Examples'],
+      },
+    }
+  },
+};
+
+export default preview;

.storybook/stories/Examples/Simulation.mdx

@@ -0,0 +1,18 @@
+import { Meta, Story } from '@storybook/blocks';
+
+import * as SimulationStories from './Simulation.stories';
+
+<Meta of={SimulationStories} />
+
+# Button
+
+Button is a clickable interactive element that triggers a response.
+
+You can place text and icons inside of a button.
+
+Buttons are often used for form submissions and to toggle elements into view.
+
+## Usage
+
+<Story of={SimulationStories.TwoDim} />
+<Story of={SimulationStories.ThreeDim} />

.storybook/stories/Examples/Simulation.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Simulation } from './Simulation';
+
+// More on how to set up stories at: https://storybook.js.org/docs/writing-stories#default-export
+const meta = {
+  title: 'Examples/Simulation',
+  component: Simulation,
+  parameters: {
+    // Optional parameter to center the component in the Canvas. More info: https://storybook.js.org/docs/configure/story-layout
+    layout: 'centered',
+    controls: {
+      disable: true,
+    }
+  },
+  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/writing-docs/autodocs
+  tags: [],
+  // More on argTypes: https://storybook.js.org/docs/api/argtypes
+  argTypes: {
+  //     storyName: {
+
+  //     }
+  // visType: {
+
+  // }
+  // record: {
+
+  // }
+  // looped: {
+
+  // }
+  // controller: {
+
+  // }
+  // showTrails: {
+
+  // }
+  // showDebugInfo: {
+
+  // }
+  // maxFrameRate: {
+
+  // }
+  // maxTrailLength: {
+
+  // }
+  },
+  // Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked: https://storybook.js.org/docs/essentials/actions#action-args
+  args: {  },
+} satisfies Meta<typeof Simulation>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+export const TwoDim: Story = {
+  args: {
+    storyName: '2D',
+  },
+};
+
+export const ThreeDim: Story = {
+  args: {
+    storyName: '3D',
+    visType: '3D',
+  },
+};

.storybook/stories/Examples/Simulation.tsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import { CelestialBody, ControllerType, Gravity, Simulation as NbodySimulation, RungeKutta4Sim, State, Universe, Vector3, VisType } from "../../../src/index";
+
+interface SimulationProps {
+  storyName: string;
+  visType?: VisType;
+  record?: boolean;
+  looped?: boolean;
+  controller?: ControllerType;
+  showTrails?: boolean;
+  showDebugInfo?: boolean;
+  maxFrameRate?: number;
+  maxTrailLength?: number;
+}
+
+/**
+ * Primary UI component for user interaction
+ */
+export const Simulation = ({
+  storyName = 'default',
+  visType = '2D',
+  record = false,
+  looped = true,
+  controller = 'ui',
+  showTrails = false,
+  showDebugInfo = true,
+  maxFrameRate = -1,
+  maxTrailLength = 100,
+  ...props
+}: SimulationProps) => {
+  const divId = 'demo-' + storyName;
+  const force = new Gravity(1);
+  const a = new CelestialBody(
+    "a",
+    1,
+    new Vector3(-0.97000436, 0.24308753, 0),
+    new Vector3(0.466203685, 0.43236573, 0),
+    new Vector3(0, 0, 0)
+  );
+  const b = new CelestialBody(
+    "b",
+    1,
+    new Vector3(0.97000436, -0.24308753, 0),
+    new Vector3(0.466203685, 0.43236573, 0),
+    new Vector3(0, 0, 0)
+  );
+  const c = new CelestialBody(
+    "c",
+    1,
+    new Vector3(0, 0, 0),
+    new Vector3(-2 * 0.466203685, -2 * 0.43236573, 0),
+    new Vector3(0, 0, 0)
+  );
+  const universe: Universe = new Universe({
+    label: "a",
+    currState: new State([a, b, c]),
+    color: "rgba(254, 209, 106, 1)",
+    simFunc: new RungeKutta4Sim(force, [1, 2, 2, 1]),
+  }
+  );
+
+  const simulation = new NbodySimulation([universe], {
+    visType,
+    record,
+    looped,
+    controller,
+    showTrails,
+    showDebugInfo,
+    maxFrameRate,
+    maxTrailLength,
+  });
+
+  return (
+    <div
+      id={divId}
+      style={{width: 600, height: 600, position: 'relative'}}
+      ref={() => simulation.start(divId, 600, 600)}>
+    </div>
+  );
+};

.storybook/stories/Install.mdx

@@ -0,0 +1,20 @@
+import { Meta, Story } from '@storybook/blocks';
+
+<Meta title="Getting Started/Installation" />
+
+# Installation guide
+nbody is available on the npm registry as [nbody](https://www.npmjs.com/package/nbody). Simply follow the following install commands based on your package manager. Since nbody relies on [three](https://threejs.org/) and [Plotly.js](https://plotly.com/javascript/) for visualization of the simulations, they have to be installed alongside nbody.
+
+If you are using Typescript, you may also have to install type definitions as well.
+
+
+```bash
+npm install nbody three plotly.js-dist
+npm install --save-dev @types/three @types/plotly.js
+```
+or 
+
+```bash
+yarn add nbody three plotly.js-dist
+yarn add -D @types/three @types/plotly.js
+```

.storybook/stories/Integration.mdx

@@ -0,0 +1,123 @@
+import { Meta, Story } from '@storybook/blocks';
+
+<Meta title="Getting Started/Integration" />
+
+# Integration
+
+Once installed into your `node_modules`, you can use **nbody** in your choice of your frontend framework just like you would any other client side library.
+
+## Table of Contents
+- [Compatible Frameworks](#compatible-frameworks)
+- [React](#react)
+- [Typescript](#typescript)
+
+## Compatible Frameworks
+
+Following combinations of Frontend frameworks + build tools + dev tools have been tested to be compatible with nbody. Consider raising a [request](https://github.com/source-academy/nbody/issues) if any frameworks are missing. Additionally do consider contributing to the project directly.
+
+- React + Vite
+- React + Vite + TS
+- React + Webpack
+- React + Webpack + TS
+
+## React
+
+```javascript
+import {
+  CelestialBody, Gravity, VelocityVerletSim, State, Universe, Simulation, RungeKutta4Sim, ExplicitEulerSim, SemiImplicitEulerSim, CoMTransformation, Vector3
+} from "nbody";
+
+function run(divId, width, height) {
+  let g = 1;
+
+  let force = new Gravity(g);
+  let sim = new VelocityVerletSim(force);
+
+  let a = new CelestialBody(
+    "a",
+    1,
+    new Vector3(-0.97000436, 0.24308753, 0),
+    new Vector3(0.466203685, 0.43236573, 0),
+    new Vector3(0, 0, 0)
+  );
+
+  let b = new CelestialBody(
+    "b",
+    1,
+    new Vector3(0.97000436, -0.24308753, 0),
+    new Vector3(0.466203685, 0.43236573, 0),
+    new Vector3(0, 0, 0)
+  );
+
+  let c = new CelestialBody(
+    "c",
+    1,
+    new Vector3(0, 0, 0),
+    new Vector3(-2 * 0.466203685, -2 * 0.43236573, 0),
+    new Vector3(0, 0, 0)
+  );
+
+  let state = new State([a, b, c]);
+
+  let universe = new Universe({
+    label: "1",
+    currState: state.clone(),
+    color: "rgba(112, 185, 177, 1)",
+    simFunc: sim,
+  });
+
+  let simulation = new Simulation(universe, {
+    visType: "3D",
+    showTrails: true,
+    controller: "ui",
+  });
+
+  simulation.start(divId, 800, 800, width, height);
+}
+
+function App() {
+  return (
+    <div
+      id="demo-canvas"
+      style={{
+        overflow: "hidden",
+        width: "800px",
+        height: "800px",
+        position: "relative",
+      }}
+      ref={() => run("demo-canvas", 800, 800)}
+    ></div>
+  );
+}
+
+export default App;
+```
+
+## Typescript
+
+```typescript
+class TranslateZTransformation implements Transformation {
+  transform(state: State, deltaT: number): State {
+    const newState = state.clone();
+    newState.bodies.forEach((body) => {
+      body.position.z += 1;
+    });
+    return newState;
+  }
+}
+
+function run(divId: string) {
+  ...
+
+  let universe: Universe = new Universe({
+    label: "Translated Universe",
+    currState: new State([a, b, c]),
+    color: "rgba(254, 209, 106, 1)",
+    simFunc: new VelocityVerletSim(new Gravity(1)),
+    transformations: [new TranslateZTransformation()]
+    }
+  );
+
+  ...
+}
+```

.storybook/stories/Nbody.mdx

@@ -0,0 +1,27 @@
+import { Meta, Story } from "@storybook/blocks";
+
+<Meta title="Getting started/nbody" />
+
+[API](https://source-academy.github.io/nbody/api)
+
+# nbody
+
+A JS/TS library to configure, simulate and visualize nbody simulations in the browser.
+
+# Background
+
+The [**n-body problem**](https://en.wikipedia.org/wiki/N-body_problem), a cornerstone of celestial mechanics, involves predicting the motions of multiple objects interacting **gravitationally**. While solvable analytically for [two-bodies](https://en.wikipedia.org/wiki/Two-body_problem), we rely on computer simulations using numerical integration methods for three or more.
+
+This project aims to bridge the _space_ between accuracy, accessibility, performance and education. With this JS/TS library, you can
+
+- **Effortlessly configure** your system of bodies.
+- **Simulate with flexibility** utilizing various accurate and/or performant numerical integration methods or even write you own.
+- **Visually explore** and immerse yourself with customizable 2D and 3D visualizations and intuitive UI controls
+
+# Development
+
+**nbody** is maintained by the open-source [Source Academy](https://github.com/source-academy/) development community based in National University of Singapore. Anyone from anywhere is free to contribute to the project and the community.
+
+# Contributors
+
+- [Yeluri Ketan](https://yeluriketan.vercel.app/) - Creator and Maintainer