set up vocs (#2)

fix

update scripts

README.md

@@ -16,7 +16,7 @@ A React Component Library, Where Buttons Look Like Buttons.
 -   NPM: [@moai/core](http://npmjs.com/package/@moai/core)
 -   License: [MIT](./LICENSE)
 
-### Contributing
+## Contributing
 
 -   [Contributing Overview](./.github/CONTRIBUTING.md): Report bugs, request features, write code and improve documentation.
 -   [Design Principles](https://moai.thien.do/?path=/docs/intro-principles--page): The unique traits that lead Moai's design and development.

new-docs/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+/public

new-docs/README.md

@@ -0,0 +1 @@
+This is a [Vocs](https://vocs.dev) project bootstrapped with the Vocs CLI.

new-docs/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "new-docs",
+	"version": "0.0.0",
+	"type": "module",
+	"scripts": {
+		"_start": "vocs dev",
+		"_build": "vocs build"
+	},
+	"dependencies": {
+		"@types/react": "latest",
+		"color": "^4.2.3",
+		"react": "latest",
+		"react-dom": "latest",
+		"typescript": "latest",
+		"vocs": "latest"
+	},
+	"devDependencies": {
+		"@types/color": "^3.0.6"
+	}
+}

new-docs/pages/draft/extension.stories.mdx

@@ -0,0 +1,3 @@
+# Customizing Moai
+
+TBA

new-docs/pages/draft/showcase.stories.mdx

@@ -0,0 +1,12 @@
+# Showcase (Draft)
+
+Production projects that use Moai:
+
+-   vim.md - close - commercial
+-   DiagramPlus (TablePlus) - close - free
+-   TablePlus Toolkit - close - free
+-   Liquid Chain Explorer - open - free
+
+UI kit based on Moai:
+
+-   Be's BanhMi

new-docs/pages/global.d.ts

@@ -0,0 +1,4 @@
+declare module "*.module.css" {
+	const classes: { readonly [key: string]: string };
+	export default classes;
+}

new-docs/pages/index.mdx

@@ -0,0 +1,20 @@
+---
+layout: landing
+---
+
+import { HomePage } from "vocs/components";
+
+<HomePage.Root>
+	<HomePage.Logo />
+	<HomePage.Tagline>
+		A React Component Library, Where Buttons Look Like Buttons.
+	</HomePage.Tagline>
+	<HomePage.Buttons>
+		<HomePage.Button href="/intro/quick-start" variant="accent">
+			Quick start
+		</HomePage.Button>
+		<HomePage.Button href="https://github.com/thien-do/moai">
+			GitHub
+		</HomePage.Button>
+	</HomePage.Buttons>
+</HomePage.Root>

new-docs/pages/intro/principles.stories.mdx

@@ -0,0 +1,43 @@
+# Principles
+
+Some principles lead the design and development of Moai. They are the unique traits that set Moai apart from other UI kits. Reading them is the best way to know if Moai is "for" you.
+
+### Usable
+
+> "Two of the most important characteristics of good design are discoverability and understanding."
+>
+> — Donald A. Norman, The Design of Everyday Things
+
+Moai is not designed to look "impressive" or "trendy". Moai is designed to communicate [how things work][htw]. Buttons look raised because users can click on them. Text boxes look sunken because users can fill in them. Moai employs subtle-yet-meaningful visual [signifiers][snf] to help your users understand your products.
+
+[htw]: https://www.nngroup.com/articles/mental-models/
+[snf]: http://jnd.org/dn.mss/signifiers_not_affordances.html
+
+### Accessible
+
+> "The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect."
+>
+> — Tim Berners-Lee, W3C Director and inventor of the World Wide Web
+
+Moai is friendly not only to humans but also to the [machines][sr] that help humans. Components always strive for standard, [semantic][smt] HTML, from simple `label` to complex `table`. For non-standard use cases, like tooltips and icon-only buttons, [WAI-ARIA][aria] shines.
+
+[sr]: https://en.wikipedia.org/wiki/Screen_reader
+[smt]: https://en.wikipedia.org/wiki/Semantic_HTML
+[aria]: https://www.w3.org/WAI/standards-guidelines/aria/
+
+### Interoperable
+
+Moai leverages the ecosystems it lives in. All components are designed with [Web's standards][web] and [React's principles][react] in mind, so they usually work well with other technologies and tools in the ecos, from popular [icon sets][icon] to leading [form builders][form].
+
+[web]: https://html.spec.whatwg.org/
+[react]: https://reactjs.org/docs/design-principles.html
+[icon]: /docs/patterns-icon--primary
+[form]: /docs/patterns-form--primary
+
+### Extensible
+
+> "Software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification"
+>
+> — Bertrand Meyer, Object-Oriented Software Construction
+
+Moai goes the extra mile to protect itself from common-but-unsafe modification, like "className" and "style" prop. Instead, Moai offers strictly typed interfaces for safe and maintainable customization, from buttons' background to inputs' paddings.

new-docs/pages/intro/proper-start.stories.mdx

@@ -0,0 +1,123 @@
+# Proper Start
+
+If you are in a hurry, see the [Quick Start] instead. This page covers the same
+steps but with more explanation and tips.
+
+[quick start]: /story/guides-quick-start--page
+
+## 1. Install
+
+The [@moai/core] package is the basis of the Moai kit. It provides all basic
+components, from buttons to dialogs and tables, along with necessary CSS.
+Install it with your package manager:
+
+```
+yarn add @moai/core
+```
+
+-   It has [react] and [react-dom] as peer dependencies, so make sure they are
+    installed. (Which is usually the case if you use a framework like [Next.js] or
+    [CRA].)
+-   Moai is written entirely in TypeScript (strict mode!) so all typings are
+    bundled in the packages.
+
+[typing]: https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html
+[react]: https://www.npmjs.com/package/react
+[react-dom]: https://www.npmjs.com/package/react-dom
+[@moai/core]: https://www.npmjs.com/package/@moai/core
+[next.js]: https://nextjs.org/
+[cra]: https://create-react-app.dev/
+
+## 2. Setup
+
+There are a few things you need to do **once** before using Moai's components:
+
+### 2.1. Styling
+
+Import Moai's CSS bundle at your app root. This contains CSS for all components
+in the "core" package.
+
+```tsx
+import "@moai/core/dist/bundle.css";
+```
+
+-   In Next.js, use the [custom App]. In CRA, use `src/index`.
+-   The bundled CSS contains a [simple reset], so it's best to not include
+    another one.
+-   All CSS for components use [CSS Modules]. This means all class names are
+    scoped so you can use other class-based libraries like [Tailwind CSS] or
+    [Tachyons] without worrying about naming conflict.
+
+[simple reset]: https://github.com/moaijs/moai/blob/main/core/src/global.css
+[css modules]: https://github.com/css-modules/css-modules
+[tailwind css]: https://tailwindcss.com
+[tachyons]: https://tachyons.io/
+[custom app]: https://nextjs.org/docs/advanced-features/custom-app
+
+### 2.2. Theme
+
+Moai comes with both light and dark themes out of the box. However, there is no
+default, so you must explicitly set a class on your `html` tag to specify the
+theme: either `light` or `dark`.
+
+-   To avoid a [FOUC], ensure that your `html` tag has the class in the initial
+    render. This is usually done via a "template" file. In CRA, for example, set it
+    in [`public/index.html`].
+-   In Next.js, we recommend the [`next-themes`] package. It allows your users
+    to change the theme, including a "system" option, without any flashing in
+    initial render.
+
+[custom document]: https://nextjs.org/docs/advanced-features/custom-document
+[`public/index.html`]: https://create-react-app.dev/docs/using-the-public-folder/#changing-the-html
+[fouc]: https://en.wikipedia.org/wiki/Flash_of_unstyled_content
+[`next-themes`]: https://github.com/pacocoursey/next-themes
+
+### 2.3. Font (Optional)
+
+Out of the box, Moai uses [system fonts]. For example, on a modern Mac OS, you
+would see the [San Francisco] typeface. This requires no additional setup
+and is the best solution performance-wise.
+
+However, the for best visual result, we highly recommend the [Inter] typeface.
+To use it, just import the following CSS at your app's root, and Moai will use
+Inter instead:
+
+```tsx
+import "@moai/core/dist/font/remote.css";
+```
+
+-   Moai uses the [variable] version of Inter. Check browser compatibility if you
+    need to support old browsers.
+-   If your app cannot make network requests, replace "remote" with "local" in the
+    path above to use a bundled version of Inter. This may require a [special
+    setup].
+-   It is NOT recommended to use the version on Google Fonts since it lost many
+    [OpenType features].
+
+[system fonts]: https://github.com/moaijs/moai/blob/d3c7c957016b0a8de7838c35fe309384154f9f40/core/src/global.css#L54-L55
+[san francisco]: https://en.wikipedia.org/wiki/San_Francisco_(sans-serif_typeface)
+[inter]: https://rsms.me/inter/
+[variable]: https://en.wikipedia.org/wiki/Variable_font
+[instruction]: https://rsms.me/inter/#usage
+[opentype features]: https://en.wikipedia.org/wiki/List_of_typographic_features
+[special setup]: https://webpack.js.org/guides/asset-management/#loading-fonts
+
+## 3. Use the components
+
+After the setup, just import the components from the package to use. All
+components are exported at the top level:
+
+```tsx
+import { Button } from "@moai/core";
+
+export const Foo = (): JSX.Element => <Button>Hello</Button>;
+```
+
+-   Moai is distributed with an [ES6 module] version. If you are using an
+    ES6-aware bundler (such as [Rollup] or [Webpack 2+]), your app won't contain
+    the whole Moai library but only the components that you used, which may
+    significantly reduce your app size.
+
+[es6 module]: https://github.com/rollup/rollup/wiki/pkg.module
+[rollup]: https://rollupjs.org/guide/en/
+[webpack 2+]: https://webpack.js.org/guides/tree-shaking/

new-docs/pages/intro/quick-start.stories.mdx

@@ -0,0 +1,28 @@
+# Quick Start
+
+First, add the package:
+
+```
+yarn add @moai/core
+```
+
+Then, add the CSS at your app's root:
+
+```tsx
+import "@moai/core/dist/bundle.css";
+import "@moai/core/dist/font/remote.css";
+```
+
+Finally, add either `light` or `dark` class to your `html` tag:
+
+```html
+<html class="light"></html>
+```
+
+And you can use Moai's components:
+
+```tsx
+import { Button } from "@moai/core";
+
+export const Foo = (): JSX.Element => <Button>Hello</Button>;
+```

new-docs/sidebar.ts

@@ -0,0 +1,56 @@
+import { SidebarItem } from "vocs";
+import fs from "fs";
+import path from "path";
+
+function capitalize(text: string): string {
+	return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function generateSidebar(dirPath: string, parentDir: string): SidebarItem[] {
+	const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+	const items: SidebarItem[] = [];
+
+	entries.forEach((entry) => {
+		// If entry is file end with '.stories.mdx', add sidebar item with link
+		if (entry.isFile() && entry.name.endsWith(".stories.mdx")) {
+			const fileName = entry.name.replace(".stories.mdx", "");
+			if (fileName === "index") {
+				items.unshift({
+					text: capitalize(fileName.replace(/-/g, " ")),
+					link: parentDir,
+				});
+			} else {
+				items.push({
+					text: capitalize(fileName.replace(/-/g, " ")),
+					link: `${parentDir}/${fileName}`,
+				});
+			}
+			return;
+		}
+
+		// If entry is directory, add collapsable sidebar item
+		if (entry.isDirectory()) {
+			const subDirPath = path.join(dirPath, entry.name);
+			const subItems = generateSidebar(
+				subDirPath,
+				`${parentDir}/${entry.name}`,
+			);
+			if (subItems.length === 0) return;
+
+			const item = {
+				text: capitalize(entry.name),
+				collapsed: false,
+				items: subItems,
+			};
+			items.push(item);
+		}
+	});
+
+	return items;
+}
+
+const TOP_LEVEL_ORDER = ["Intro", "Patterns", "Components", "Draft"];
+export const sidebar = generateSidebar("./pages", "").sort((a, b) => {
+	return TOP_LEVEL_ORDER.indexOf(a.text) - TOP_LEVEL_ORDER.indexOf(b.text);
+});

new-docs/tsconfig.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,
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"noEmit": true,
+		"jsx": "react-jsx",
+
+		/* Linting */
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true
+	},
+	"include": ["**/*.ts", "**/*.tsx"]
+}

new-docs/vocs.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vocs";
+import { sidebar } from "./sidebar";
+
+export default defineConfig({
+	rootDir: ".",
+	title: "Moai UI Kit",
+	sidebar: sidebar,
+});