From 438ca9b0d143d27d7d5360286c463a1802617f61 Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Fri, 16 Aug 2024 16:12:02 +0700 Subject: [PATCH] docs: add how-to-use guide --- .storybook/preview.tsx | 3 + docs/AvatarIntro.mdx | 9 +-- docs/ButtonIntro.mdx | 9 +-- docs/CardIntro.mdx | 9 +-- docs/CheckboxIntro.mdx | 9 +-- docs/Introduction.mdx | 5 +- docs/MenuIntro.mdx | 9 +-- docs/SelectIntro.mdx | 9 +-- docs/SwitchIntro.mdx | 9 +-- docs/TabsIntro.mdx | 9 +-- docs/TextFieldIntro.mdx | 9 +-- docs/cli.mdx | 2 +- docs/how-to-use.mdx | 61 +++++++++++++++++++ examples/mui-treasury-playground/.gitignore | 24 ++++++++ examples/mui-treasury-playground/README.md | 39 ++++++++++++ .../mui-treasury-playground/eslint.config.js | 26 ++++++++ examples/mui-treasury-playground/index.html | 13 ++++ examples/mui-treasury-playground/package.json | 34 +++++++++++ .../mui-treasury-playground/public/vite.svg | 1 + examples/mui-treasury-playground/src/App.tsx | 15 +++++ .../src/assets/react.svg | 1 + examples/mui-treasury-playground/src/main.tsx | 21 +++++++ .../mui-treasury-playground/src/vite-env.d.ts | 1 + .../mui-treasury-playground/tsconfig.app.json | 24 ++++++++ .../mui-treasury-playground/tsconfig.json | 7 +++ .../tsconfig.node.json | 22 +++++++ .../mui-treasury-playground/vite.config.ts | 7 +++ 27 files changed, 328 insertions(+), 59 deletions(-) create mode 100644 docs/how-to-use.mdx create mode 100644 examples/mui-treasury-playground/.gitignore create mode 100644 examples/mui-treasury-playground/README.md create mode 100644 examples/mui-treasury-playground/eslint.config.js create mode 100644 examples/mui-treasury-playground/index.html create mode 100644 examples/mui-treasury-playground/package.json create mode 100644 examples/mui-treasury-playground/public/vite.svg create mode 100644 examples/mui-treasury-playground/src/App.tsx create mode 100644 examples/mui-treasury-playground/src/assets/react.svg create mode 100644 examples/mui-treasury-playground/src/main.tsx create mode 100644 examples/mui-treasury-playground/src/vite-env.d.ts create mode 100644 examples/mui-treasury-playground/tsconfig.app.json create mode 100644 examples/mui-treasury-playground/tsconfig.json create mode 100644 examples/mui-treasury-playground/tsconfig.node.json create mode 100644 examples/mui-treasury-playground/vite.config.ts diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx index 037db250..653160de 100644 --- 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 index 325f3ce0..b8327f61 100644 --- a/docs/AvatarIntro.mdx +++ b/docs/AvatarIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 5524b9bc..65c6785a 100644 --- a/docs/ButtonIntro.mdx +++ b/docs/ButtonIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 2279ed69..cecb8a30 100644 --- a/docs/CardIntro.mdx +++ b/docs/CardIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 8ab15e6e..fb322c5e 100644 --- a/docs/CheckboxIntro.mdx +++ b/docs/CheckboxIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 18a1a3b1..eb4e2992 100644 --- 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 index 455e3ab3..c30fceec 100644 --- a/docs/MenuIntro.mdx +++ b/docs/MenuIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 4515dbb2..97b9609d 100644 --- a/docs/SelectIntro.mdx +++ b/docs/SelectIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 9805cf6e..42c4164d 100644 --- a/docs/SwitchIntro.mdx +++ b/docs/SwitchIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index e0077c15..69f36240 100644 --- a/docs/TabsIntro.mdx +++ b/docs/TabsIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index 34e22f31..6a3783bc 100644 --- a/docs/TextFieldIntro.mdx +++ b/docs/TextFieldIntro.mdx @@ -3,12 +3,9 @@ import { Meta } from "@storybook/blocks"; -## 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 index c3594899..0ee5af39 100644 --- a/docs/cli.mdx +++ b/docs/cli.mdx @@ -1,6 +1,6 @@ import { Meta } from "@storybook/blocks"; - + # Command line interface diff --git a/docs/how-to-use.mdx b/docs/how-to-use.mdx new file mode 100644 index 00000000..c28c67a9 --- /dev/null +++ b/docs/how-to-use.mdx @@ -0,0 +1,61 @@ +import { Meta } from "@storybook/blocks"; + + + + + +# 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 new file mode 100644 index 00000000..a547bf36 --- /dev/null +++ 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 new file mode 100644 index 00000000..0ee2fe5e --- /dev/null +++ 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: + + + +```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: + + + +[![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 new file mode 100644 index 00000000..c4bc8f33 --- /dev/null +++ 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 new file mode 100644 index 00000000..e4b78eae --- /dev/null +++ b/examples/mui-treasury-playground/index.html @@ -0,0 +1,13 @@ + + + + + + + Vite + React + TS + + +
+ + + diff --git a/examples/mui-treasury-playground/package.json b/examples/mui-treasury-playground/package.json new file mode 100644 index 00000000..78073945 --- /dev/null +++ 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 new file mode 100644 index 00000000..e7b8dfb1 --- /dev/null +++ b/examples/mui-treasury-playground/public/vite.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/examples/mui-treasury-playground/src/App.tsx b/examples/mui-treasury-playground/src/App.tsx new file mode 100644 index 00000000..28ad4fda --- /dev/null +++ b/examples/mui-treasury-playground/src/App.tsx @@ -0,0 +1,15 @@ +import Box from "@mui/material/Box"; + +export default function App() { + return ( + + + Get blocks + + + ); +} diff --git a/examples/mui-treasury-playground/src/assets/react.svg b/examples/mui-treasury-playground/src/assets/react.svg new file mode 100644 index 00000000..6c87de9b --- /dev/null +++ b/examples/mui-treasury-playground/src/assets/react.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/examples/mui-treasury-playground/src/main.tsx b/examples/mui-treasury-playground/src/main.tsx new file mode 100644 index 00000000..990d1d01 --- /dev/null +++ b/examples/mui-treasury-playground/src/main.tsx @@ -0,0 +1,21 @@ +import { StrictMode } from "react"; +import { createRoot } from "react-dom/client"; +import CssBaseline from "@mui/material/CssBaseline"; +import { createTheme, ThemeProvider } from "@mui/material/styles"; +import App from "./App.tsx"; + +const theme = createTheme({ + cssVariables: { + colorSchemeSelector: "class", + }, + colorSchemes: { light: true, dark: true }, +}); + +createRoot(document.getElementById("root")!).render( + + + + + + , +); diff --git a/examples/mui-treasury-playground/src/vite-env.d.ts b/examples/mui-treasury-playground/src/vite-env.d.ts new file mode 100644 index 00000000..11f02fe2 --- /dev/null +++ b/examples/mui-treasury-playground/src/vite-env.d.ts @@ -0,0 +1 @@ +/// diff --git a/examples/mui-treasury-playground/tsconfig.app.json b/examples/mui-treasury-playground/tsconfig.app.json new file mode 100644 index 00000000..f0a23505 --- /dev/null +++ b/examples/mui-treasury-playground/tsconfig.app.json @@ -0,0 +1,24 @@ +{ + "compilerOptions": { + "target": "ES2020", + "useDefineForClassFields": true, + "lib": ["ES2020", "DOM", "DOM.Iterable"], + "module": "ESNext", + "skipLibCheck": true, + + /* Bundler mode */ + "moduleResolution": "bundler", + "allowImportingTsExtensions": true, + "isolatedModules": true, + "moduleDetection": "force", + "noEmit": true, + "jsx": "react-jsx", + + /* Linting */ + "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noFallthroughCasesInSwitch": true + }, + "include": ["src"] +} diff --git a/examples/mui-treasury-playground/tsconfig.json b/examples/mui-treasury-playground/tsconfig.json new file mode 100644 index 00000000..1ffef600 --- /dev/null +++ b/examples/mui-treasury-playground/tsconfig.json @@ -0,0 +1,7 @@ +{ + "files": [], + "references": [ + { "path": "./tsconfig.app.json" }, + { "path": "./tsconfig.node.json" } + ] +} diff --git a/examples/mui-treasury-playground/tsconfig.node.json b/examples/mui-treasury-playground/tsconfig.node.json new file mode 100644 index 00000000..0d3d7144 --- /dev/null +++ b/examples/mui-treasury-playground/tsconfig.node.json @@ -0,0 +1,22 @@ +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2023"], + "module": "ESNext", + "skipLibCheck": true, + + /* Bundler mode */ + "moduleResolution": "bundler", + "allowImportingTsExtensions": true, + "isolatedModules": true, + "moduleDetection": "force", + "noEmit": true, + + /* Linting */ + "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noFallthroughCasesInSwitch": true + }, + "include": ["vite.config.ts"] +} diff --git a/examples/mui-treasury-playground/vite.config.ts b/examples/mui-treasury-playground/vite.config.ts new file mode 100644 index 00000000..5a33944a --- /dev/null +++ b/examples/mui-treasury-playground/vite.config.ts @@ -0,0 +1,7 @@ +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' + +// https://vitejs.dev/config/ +export default defineConfig({ + plugins: [react()], +})