docs: add how-to-use guide

siriwatknp · Aug 16, 2024 · 438ca9b · 438ca9b
1 parent 66cce8f
commit 438ca9b
Show file tree

Hide file tree

Showing 27 changed files with 328 additions and 59 deletions.
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
@@ -38,6 +38,9 @@ const preview: Preview = {
     options: {
       storySort: {
         order: [
+          "Introduction",
+          "How to use",
+          "Command line",
           "Layout v6",
           [
             "Introduction",

diff --git a/docs/AvatarIntro.mdx b/docs/AvatarIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Avatar/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/ButtonIntro.mdx b/docs/ButtonIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Button/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/CardIntro.mdx b/docs/CardIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Card/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/CheckboxIntro.mdx b/docs/CheckboxIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Checkbox/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/Introduction.mdx b/docs/Introduction.mdx
@@ -15,10 +15,7 @@ A block is a self-contained component that can be used in any MUI UI application
 
 ## How to use a block?
 
-There are two ways to use a block:
-
-1. Copy & paste the code into your project by open a "Docs" for the block you want to use and click on the "Copy" button.
-2. Use the [CLI](/docs/cli--docs) tool to clone the block into your project.
+See the [How to use](/docs/how-to-use--docs) section for more details.
 
 ## How to contribute?
 

diff --git a/docs/MenuIntro.mdx b/docs/MenuIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Menu/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/SelectIntro.mdx b/docs/SelectIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Select/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/SwitchIntro.mdx b/docs/SwitchIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Switch/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/TabsIntro.mdx b/docs/TabsIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Tabs/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/TextFieldIntro.mdx b/docs/TextFieldIntro.mdx
@@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks";
 <Meta title="Text Field/Introduction" />
 
 <style>{`ol {
-    list-style: num;
+    list-style: decimal;
   }`}</style>
 
-## How to use
+# Introduction
 
-1. Browse the blocks and pick the one (or more) by clicking "+ ADD" button at the bottom toolbar. It will copy the command line to your clipboard.
-2. Paste the command line to your terminal at the root dir of you project and run it.
-3. You will see the block(s) you picked in `src/mui-treasury` folder.
-4. Import the block(s) to a page. It's that simple!
+Check out [how-to-use guide](/docs/how-to-use--docs) page to learn how to use blocks in your project.
diff --git a/docs/cli.mdx b/docs/cli.mdx
@@ -1,6 +1,6 @@
 import { Meta } from "@storybook/blocks";
 
-<Meta title="CLI" />
+<Meta title="Command line" />
 <style>{``}</style>
 
 # Command line interface

diff --git a/docs/how-to-use.mdx b/docs/how-to-use.mdx
@@ -0,0 +1,61 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="How to use" />
+
+<style>
+  {`
+  ol {
+    list-style: decimal;
+  }
+`}
+</style>
+
+# How to use
+
+If you haven't started a Material UI project yet, you can use one of the following playground:
+
+[![Edit on StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/siriwatknp/mui-treasury/tree/master/examples/mui-treasury-playground)
+
+[![Edit on CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/github/siriwatknp/mui-treasury/tree/master/examples/mui-treasury-playground)
+
+There are 2 ways to use the blocks:
+
+## 1. Copy and paste
+
+This is a quick way to try out a block.
+
+1. Go to the blocks that you want to clone. For example, [Card Galaxy](/story/card-galaxy--galaxy).
+2. Click "See code" on the toolbar at the top of the page
+   ![image](https://github.com/user-attachments/assets/9479d05d-97ae-44b7-896e-457cf0eda69a)
+
+3. Copy the code and paste it into your project.
+   ![image](https://github.com/user-attachments/assets/da618edd-71de-4fdd-876e-81d419264ab5)
+
+If you need to use a lot of blocks at once, I recommend using the [command line](#2-clone-blocks-through-cli) instead.
+
+## 2. Clone blocks through CLI
+
+You should have a working Material UI project before you start, or use one of these playgrounds:
+
+[![Edit on StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/siriwatknp/mui-treasury/tree/master/examples/mui-treasury-playground)
+
+[![Edit on CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/github/siriwatknp/mui-treasury/tree/master/examples/mui-treasury-playground)
+
+1. Go to the blocks that you want to **clone**. For example, [Card Galaxy](/story/card-galaxy--galaxy).
+2. Click "Add" on the toolbar at the top of the page
+   ![image](https://github.com/user-attachments/assets/c4afffe2-bc69-4d47-aecb-71ecaed77504)
+
+   Then, you will see the block appear in the selection (other blocks that are the dependencies of the block will be added as well).
+   ![image](https://github.com/user-attachments/assets/95f30627-a518-4f4e-88e6-fc8fc82d9330)
+
+3. Click "Copy" to copy the command line to your clipboard.
+   ![image](https://github.com/user-attachments/assets/3f70c65c-e542-4a07-9aa1-ccd338d3308d)
+
+4. Go to your project, open the terminal at the root directory, and paste the command line.
+   ![image](https://github.com/user-attachments/assets/db480cf0-5e29-441f-8f72-ad125b10e8f3)
+
+   After running the command, you will see the block(s) in the `src/mui-treasury` folder.
+
+5. Import the block to a page. It's that simple!
+
+For more details about the command line interface, check out the [CLI documentation](/docs/command-line--docs).
diff --git a/examples/mui-treasury-playground/.gitignore b/examples/mui-treasury-playground/.gitignore
@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
diff --git a/examples/mui-treasury-playground/README.md b/examples/mui-treasury-playground/README.md
@@ -0,0 +1,39 @@
+# MUI Treasury Playground - Vite.js in TypeScript example
+
+This is a [Vite](https://vitejs.dev/) project bootstrapped using [`create-vite`](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) with [Material UI](https://mui.com/material-ui/getting-started/) installed.
+
+## How to use
+
+Download the example:
+
+<!-- #default-branch-switch -->
+
+```bash
+curl https://codeload.github.com/siriwatknp/mui-treasury/tar.gz/next | tar -xz --strip=2 mui-treasury-master/examples/mui-treasury-playground
+cd mui-treasury-playground
+```
+
+Install it and run:
+
+```bash
+yarn install
+yarn dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) with your browser to see the result.
+
+or:
+
+<!-- #default-branch-switch -->
+
+[![Edit on StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/siriwatknp/mui-treasury/tree/master/examples/mui-treasury-playground)
+
+[![Edit on CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/github/siriwatknp/mui-treasury/tree/master/examples/mui-treasury-playground)
+
+## Learn more
+
+To learn more about this example:
+
+- [MUI Treasury](https://mui-treasury.com) - Get all the blocks for FREE.
+- [Material UI](https://mui.com/material-ui/getting-started/) - learn about Material UI components and API.
+- [Vite documentation](https://vitejs.dev/) - learn about Vite features and API.
diff --git a/examples/mui-treasury-playground/eslint.config.js b/examples/mui-treasury-playground/eslint.config.js
@@ -0,0 +1,26 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config({
+  extends: [js.configs.recommended, ...tseslint.configs.recommended],
+  files: ['**/*.{ts,tsx}'],
+  ignores: ['dist'],
+  languageOptions: {
+    ecmaVersion: 2020,
+    globals: globals.browser,
+  },
+  plugins: {
+    'react-hooks': reactHooks,
+    'react-refresh': reactRefresh,
+  },
+  rules: {
+    ...reactHooks.configs.recommended.rules,
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+})
diff --git a/examples/mui-treasury-playground/index.html b/examples/mui-treasury-playground/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React + TS</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/mui-treasury-playground/package.json b/examples/mui-treasury-playground/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "mui-treasury-layout-vite",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@emotion/react": "latest",
+    "@emotion/styled": "latest",
+    "@mui/icons-material": "next",
+    "@mui/material": "next",
+    "react": "latest",
+    "react-dom": "latest"
+  },
+  "devDependencies": {
+    "@eslint/js": "latest",
+    "@types/react": "latest",
+    "@types/react-dom": "latest",
+    "@vitejs/plugin-react": "latest",
+    "eslint": "latest",
+    "eslint-plugin-react-hooks": "latest",
+    "eslint-plugin-react-refresh": "latest",
+    "globals": "latest",
+    "mui-treasury": "latest",
+    "typescript": "latest",
+    "typescript-eslint": "latest",
+    "vite": "latest"
+  }
+}
diff --git a/examples/mui-treasury-playground/public/vite.svg b/examples/mui-treasury-playground/public/vite.svg
diff --git a/examples/mui-treasury-playground/src/App.tsx b/examples/mui-treasury-playground/src/App.tsx
@@ -0,0 +1,15 @@
+import Box from "@mui/material/Box";
+
+export default function App() {
+  return (
+    <Box sx={{ display: "grid", placeItems: "center" }}>
+      <a
+        href="https://mui-treasury.com"
+        target="_blank"
+        rel="noreferrer noopener"
+      >
+        Get blocks
+      </a>
+    </Box>
+  );
+}
diff --git a/examples/mui-treasury-playground/src/assets/react.svg b/examples/mui-treasury-playground/src/assets/react.svg