@jaouan/labosaurus v0.0.6

Labosaurus

Labosaurus provides interactive features to Docusaurus, useful for training purposes.

✨ Live demo here!, or (with Google authentication), or (with fake authentication)
🧪 Lab example here!, or (with Google authentication), or (with fake authentication)

How to install

Install Labosaurus :

npm install @jaouan/labosaurus

Inside your Docusaurus repository, create a file src/theme/Root.tsx (or jsx) :

import { GoogleLogin, LabosaurusRoot, firebaseAuthProvider, firebaseStoreProvider } from '@jaouan/labosaurus';

// If you want to use Firebase. You can use something else if you want.
import * as firebase from 'firebase/app';
export const app = firebase.initializeApp(... firebaseConfig ...);

export default function Root({ children }) {
  return (
    <LabosaurusRoot
      config={{
        storeProvider: firebaseStoreProvider(app), // Uses Firestore to display/hide Hidden blocks.
        authProvider: firebaseAuthProvider(app), // Uses Firebase auth.
        loginElement: () => <GoogleLogin /> // Displays a "Sign in with Google" button.
      }}
    >
      {children}
    </LabosaurusRoot>
  );
}

Features

Slide mode

Adds a space before each title to facilitate presentation. Enable it by pressing Option+Shift+S.

Hidden block

Allows to hide/show content from all readers in realtime.
Can be plugged to any realtime sources, such as Firestore, your own API or anything else.

Only administrator can show/hide hidden blocks.
If you use firebase/firestore, you have to create 2 collections :

• hidden : Labosaurus will use it to store the state of hidden groups.
• users : Labosaurus will use it to check if the connected user is an administrator. For each administrator, create a document with user's email as id, and a field admin: true. Ensure to secure your collection.

Parameters :

• until : The sequential number of the block. Displaying a block with until=N will display all blocks <N of the current group.
• group (optional) : Hidden block group (default by default).

• label (optional) : Hidden label.

import { Hidden } from "@jaouan/labosaurus";

<Hidden until={100}>
... Content ...
</Hidden>

<Hidden until={101}>
If I'm visible, the previous block is also visible.
</Hidden>

<Hidden group="foo" until={1} label="I'm hidden">
I'm in my own group. I'm not affected by others blocks.
</Hidden>

Use Firestore to get realtime synchronization :

export default function Root({ children }) {
  return (
    <LabosaurusRoot
      config={{
        ...
        storeProvider: firebaseStoreProvider(app),
      }}
    >
      {children}
    </LabosaurusRoot>
  );
}

... or anything else :

<LabosaurusRoot
    config={{
    ...
    storeProvider: {
        dispatch: ...
        get: ...
        subscribe: ...
    },
    }}
>
    {children}
</LabosaurusRoot>

Hint

Displays a hint.

import { Hint } from "@jaouan/labosaurus";

<Hint>A hint</Hint>

Question

Displays a simple question.
Answer cannot be seen in the DOM, but could be found in sources (not easily).

Parameters :

• label : The... label.
• answer : The... answer. It can be a string, or an object with details. Details is displayed after the user made his choice.
• wrongAnswers : An array of wrong answers. It can be a string, or an object with details.

• onAnswer (optional) : On answer callback.

import { SimpleQuestion } from "@jaouan/labosaurus";

<SimpleQuestion
  label="🫵 What's the weather like today?"
  answer="Sunny"
  wrongAnswers={["Cloudy", "Rainy"]}
  onAnswer={onAnswer}
/>

<SimpleQuestion
  label="🫵 What's the weather like today?"
  answer={{
    label: "Sunny",
    details:
      "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
  }}
  wrongAnswers={[
    {
      label: "Cloudy",
      details:
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
    },
    {
      label: "Rainy",
      details:
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
    },
  ]}
/>

Browser Window

Just an integration of Facebook's Browser Window.

import { BrowserWindow } from '@jaouan/labosaurus';

<BrowserWindow url="https://my-website">
    Hello world
</BrowserWindow>

Admin/User only

Displays a content only if user is an admin, or not.

import { AdminOnly, UserOnly } from '@jaouan/labosaurus';

<AdminOnly>If you see this, then you are an admin.</AdminOnly>
<UserOnly>If you see this, then you are a user, but not an admin.</UserOnly>

Blur Flow

This displays blurry steps, which the user can discover through an interactive experience.

Parameter :

• unblurred : Disable blur, useful for the first step.

import { BlurFlow, BlurFlowStep, unblurNextStep } from '@jaouan/labosaurus';

<BlurFlow>
  <BlurFlowStep unblurred={true}>
    <button onClick={unblurNextStep}>Reveal next step</button>
  </BlurFlowStep>
  <BlurFlowStep>
    Hello
    <button onClick={unblurNextStep}>Reveal next step</button>
  </BlurFlowStep>
  <BlurFlowStep>
    Bye
  </BlurFlowStep>
</BlurFlow>

Authentication

By using LabosaurusRoot, the user will be prompted to authenticate.
You can use anything you want to authenticate.
Labosaurus provides a Firebase authentication (Google oAuth), but you can highly customize authentication and use others access manager, or your own API, or nothing.

Using Firebase :

import * as firebase from 'firebase/app';
import { LabosaurusRoot, GoogleLogin, firebaseAuthProvider } from '@jaouan/labosaurus';

export const app = firebase.initializeApp({ /* firebase config */ });

export default function Root({ children }) {
  return (
    <LabosaurusRoot
      config={{
        authProvider: firebaseAuthProvider(app), // Uses Firebase auth.
        loginElement: () => <GoogleLogin /> // Displays a "Sign in with Google" button.
        ...
      }}
    >
      {children}
    </LabosaurusRoot>
  );
}

... or anything else :

<LabosaurusRoot
    config={{
    authProvider: {
        login: async () => { ... },
        logout: async () => { ... },
        isAdmin: async () => { return true|false },
        getUser: () => { return "string"|undefined; },
        onUser: (callback) => { // Labosaurus subscribes to user login/logout.
        ...
        callback(user); // Triggers callback immediately.
        return unsubscribeFunction;
        }
    },
    loginElement: () => {
        const { authProvider } = useContext<LabosaurusConfig>(LabosaurusContext);
        return <button onClick={authProvider.login}>Login</button>;
    }
    }}
>
    {children}
</LabosaurusRoot>