GitBook: [#5] No subject

lilingxi01 · gitbook-bot · commit 9c5b62b49ae8 · 2022-07-07T02:24:04.000Z
diff --git a/.gitbook/assets/Launchpad JS Cover (1).png b/.gitbook/assets/Launchpad JS Cover (1).png
diff --git a/.gitbook/assets/Launchpad JS Cover.png b/.gitbook/assets/Launchpad JS Cover.png
diff --git a/README.md b/README.md
@@ -1,2 +1,72 @@
-# launchpad-js-docs
-Launchpad Docs - The documentation repo for Launchpad (JS) library.
+---
+description: A modern API hook management system.
+layout: landing
+---
+
+# Meet the Launchpad
+
+
+
+![](<.gitbook/assets/Launchpad JS Cover (1).png>)
+
+{% hint style="info" %}
+**WIP:** This documentation is still a Work In Progress. We are happy to hear from you about any suggestion or any issue that we have!
+{% endhint %}
+
+Launchpad helps you quickly and painlessly integrate the front-end user interface with API calls (or mock calls) throughout the entire life cycle of your application.
+
+It is a brand new idea on modularizing the fetching session (the API call from server to client, or a pure local call that happens behind the UI codes) and being ease with any change that may happen on an API algorithm (or even the mock one).
+
+With Launchpad, you can define an API hook by writing its schema – including how every state turns, how API request will be fired, and everything you can imagine.
+
+The coolest thing is that UI developer can call API by simply calling the hook function, with loading state built-in and their favorite objects as parameters.
+
+## Understanding the Architecture
+
+Launchpad is an additional layer lying between the front-end application and API calls. A Launchpad session can take input, convert arguments into proper JSON, and then send package to the back-end. When back-end replies, Launchpad will update the exposed state variable based on how it was configured.
+
+So in the low-level, Launchpad is simply wrapping the essential algorithm by using hooks, and exposing most-needed APIs for a session. It saves a lot of time for UI developers to write fetching algorithm and manage annoying states (e.g. loading, error, and more) in UI files.
+
+## Getting Started
+
+### Guides: Make your first step
+
+Follow our handy guides to get started on the basics as quickly as possible:
+
+{% content-ref url="guides/installation.md" %}
+[installation.md](guides/installation.md)
+{% endcontent-ref %}
+
+{% content-ref url="guides/your-first-session.md" %}
+[your-first-session.md](guides/your-first-session.md)
+{% endcontent-ref %}
+
+{% hint style="info" %}
+**Why guides:** Follow our guide will be the best way to understand why you may need to use Launchpad. Please understand that not everyone needs it, so just use-it-when-you-need.
+{% endhint %}
+
+### Fundamentals: Dive a little deeper
+
+Learn the fundamentals of Launchpad to get a deeper understanding of our main features:
+
+Want to build an API call that is not just a simple call? Follow our example to make sure that you are using it right!
+
+{% content-ref url="fundamentals/design-a-complex-session.md" %}
+[design-a-complex-session.md](fundamentals/design-a-complex-session.md)
+{% endcontent-ref %}
+
+Want to integrate Launchpad with authorization? We can handle the authorization stuff for you, built-in. Check our guide on authorization flow and you are good to go!
+
+{% content-ref url="fundamentals/authorization-flow.md" %}
+[authorization-flow.md](fundamentals/authorization-flow.md)
+{% endcontent-ref %}
+
+Want to make some changes globally? See if you can do that by setting up a configuration file!
+
+{% content-ref url="fundamentals/configuration.md" %}
+[configuration.md](fundamentals/configuration.md)
+{% endcontent-ref %}
+
+## Credits
+
+Greatly thanks to Alex (Chaolong) for giving the idea on the name of some API properties.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -0,0 +1,27 @@
+# Table of contents
+
+* [Meet the Launchpad](README.md)
+
+## Guides
+
+* [Installation](guides/installation.md)
+* [Your First Session](guides/your-first-session.md)
+
+## Fundamentals
+
+* [Design a complex session](fundamentals/design-a-complex-session.md)
+* [Authorization flow](fundamentals/authorization-flow.md)
+* [Configuration](fundamentals/configuration.md)
+
+## Migration
+
+* [v0.0 -> v0.1](migration/v0.0-greater-than-v0.1.md)
+
+## API
+
+* [Session API](api/session-api.md)
+* [Ignition API](api/ignition-api.md)
+
+## About
+
+* [Changelog](about/changelog.md)
diff --git a/about/changelog.md b/about/changelog.md
@@ -0,0 +1,2 @@
+# Changelog
+
diff --git a/api/ignition-api.md b/api/ignition-api.md
@@ -0,0 +1,2 @@
+# Ignition API
+
diff --git a/api/session-api.md b/api/session-api.md
@@ -0,0 +1,5 @@
+# Session API
+
+{% hint style="info" %}
+**Good to know:** depending on the product you're building, it can be useful to explicitly document use cases. Got a product that can be used by a bunch of people in different ways? Maybe consider splitting it out!
+{% endhint %}
diff --git a/fundamentals/authorization-flow.md b/fundamentals/authorization-flow.md
@@ -0,0 +1,5 @@
+# Authorization flow
+
+{% hint style="info" %}
+**Good to know:** Splitting your product into fundamental concepts, objects, or areas can be a great way to let readers deep dive into the concepts that matter most to them.
+{% endhint %}
diff --git a/fundamentals/configuration.md b/fundamentals/configuration.md
@@ -0,0 +1,2 @@
+# Configuration
+
diff --git a/fundamentals/design-a-complex-session.md b/fundamentals/design-a-complex-session.md
@@ -0,0 +1,15 @@
+---
+description: >-
+  Launchpad makes building a complex session easy. Follow this documentation and
+  get a sense on how you can use most out of it!
+---
+
+# Design a complex session
+
+## What is a session?
+
+### Session Reusability
+
+For reusability, you can configure a session and ignite it as many as you like, and wherever you want.
+
+The recommended way to configure the launchpad session is writing them in a separate file, thus developers can maintain the API caller without changing the code at UI section.
diff --git a/guides/installation.md b/guides/installation.md
@@ -0,0 +1,20 @@
+# Installation
+
+The package is released on different platforms for different programming languages. Pick the one you are using, and follow the instruction to install the Launchpad!
+
+## JavaScript / TypeScript
+
+{% tabs %}
+{% tab title="React" %}
+The package for React is published on NPM. You can use following command to install it into your project.
+
+```bash
+npm install @taci-tech/launchpad-js
+```
+{% endtab %}
+
+{% tab title="Svelte" %}
+The Svelte version is not released yet. Please check back later.
+{% endtab %}
+{% endtabs %}
+
diff --git a/guides/your-first-session.md b/guides/your-first-session.md
@@ -0,0 +1,85 @@
+---
+description: >-
+  There are only two steps to use Launchpad: create a session, and then ignite
+  it. In this example, I am going to show you how to create your first Launchpad
+  session and how to ignite it!
+---
+
+# Your First Session
+
+## What is a Session?
+
+You can understand that one session is one API caller in a context. A context could be a page, a modal, a function, a component, and not necessary their children.
+
+## Understand the Session
+
+There are four lifecycles in a Launchpad session:
+
+* **On Start:** It executes when the session is first inserted into the code. Usually happens before a page is loading. In React, it is the start value of a state, when no any `useEffect` is executed.
+* **On Mount:** It executes when the session is mounted into the client. Usually happens when a page is loaded, a component is loaded, or an application is loaded. In React, it is the first `useEffect`.
+* **On Override:** Most of the APIs require information from front-end (e.g. UUID, filter settings, etc.). So, _Override_ is the behavior that the front-end are setting parameters of the session. Launchpad can then re-make the API call, update information, or do anything you need.
+* **On Unmount:** It executes when the session is going to be unmounted from the client. Usually happens when the lifecycle of a page is ended. You can unregister the listeners that were registered when page was mounted, or you can do anything you need. In React, it can be understand as the return function of an empty `useEffect` function.
+
+## Smallest Example
+
+{% tabs %}
+{% tab title="React" %}
+{% hint style="info" %}
+In this example, we are using JavaScript.
+{% endhint %}
+
+### Example
+
+A session object is fairly simple –– just a JavaScript object notation.
+
+In this example, we are not going to send an API call because that is actually optional to the session! We will mention that in the _Fundamental_ section.
+
+```javascript
+const test = () => {
+    return {
+        // The start value.
+        onStart: () => null,
+        // The callback function when the session is mounted.
+        onMount: ({ setState }) => {
+            setState(1);
+        },
+        // The callback function when the `setParam` is called.
+        onOverride: ({ state, setState, newValue }) => {
+            setState(state + newValue);
+        },
+    };
+};
+```
+
+The reason we wrap it as a function and then return a JSON is that we can have local variables inside the scope of this function. So you can use some variables to store things between different stages. But please be careful on what you store because it may violate the rule of React hook.
+
+You have done creating the session! Now, let us ignite it in React.
+
+It is similar to other hooks –– we got your back with a hook function `useLPSession`.
+
+```javascript
+const YourFunctionalComponent = () => {
+    const { data, setParam } = useLPSession(test());
+    return (...);
+}
+```
+
+That is it! After that, you have a state variable `data` that has the information you need, and an override function `setParam` to send information to the session. Every time you call `setParam` will update the `data` automatically based on your session settings.
+{% endtab %}
+
+{% tab title="Svelte" %}
+Svelte version is still under development. Check back later!
+{% endtab %}
+{% endtabs %}
+
+## Why Launchpad Session?
+
+You may feel that the Launchpad is over-powered in this case. The same functionality can also be achieved by using `useState`. But here are some use cases that you may want to use Launchpad over vanilla hooks:
+
+* When you have an algorithm that may need to be changed over time. You can choose to write a function and then call the function before every state set. In a collaborative scenario, it is not perfect. By using Launchpad, the only things you exposed to other folks (who use your session) are the returned data, a simple set function, and a built-in loading indicator. It is safer, cleaner, and easier.
+* When things become complicated (e.g. You are going to make a fetch request with the given data and set the result onto the state). If you choose vanilla hooks, you will write a bunch of things, which make your code not intuitive and decrease the reusability between different API calls.
+
+{% hint style="warning" %}
+**Maintainability:** In general, we recommend to write the session in a file that separates from the front-end UI components for a better maintainability. However, it is just an object notation, so you can write it wherever you like!
+{% endhint %}
+
diff --git a/migration/v0.0-greater-than-v0.1.md b/migration/v0.0-greater-than-v0.1.md
@@ -0,0 +1,10 @@
+# v0.0 -> v0.1
+
+In this update, we made a significant change on a property name.
+
+{% tabs %}
+{% tab title="React" %}
+* **One of the exposed igniter properties has a new name!** We changed `setData` to `setParam` to avoid further confusion on passing parameters into the launchpad. **Be sure to replace all** `setData` to `setParam`.
+{% endtab %}
+{% endtabs %}
+
