Add Component Example (#2203)

* Add Component Example

* chore(lint): Prettier fix

* nit: improve implementation

* nit: Update documentation

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

16 files changed, 251 insertions, 0 deletions

diff --git a/examples/component/.gitignore b/examples/component/.gitignore
new file mode 100644
index 000000000..d436c6dad
--- /dev/null
+++ b/examples/component/.gitignore
@@ -0,0 +1,18 @@
+# build output
+dist
+
+# dependencies
+node_modules/
+.snowpack/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
diff --git a/examples/component/.npmrc b/examples/component/.npmrc
new file mode 100644
index 000000000..65922326b
--- /dev/null
+++ b/examples/component/.npmrc
@@ -0,0 +1,2 @@
+## force pnpm to hoist 
+shamefully-hoist = true
diff --git a/examples/component/.stackblitzrc b/examples/component/.stackblitzrc
new file mode 100644
index 000000000..43798ecff
--- /dev/null
+++ b/examples/component/.stackblitzrc
@@ -0,0 +1,6 @@
+{
+  "startCommand": "npm start",
+  "env": {
+    "ENABLE_CJS_IMPORTS": true
+  }
+}
\ No newline at end of file
diff --git a/examples/component/README.md b/examples/component/README.md
new file mode 100644
index 000000000..76492bd28
--- /dev/null
+++ b/examples/component/README.md
@@ -0,0 +1,45 @@
+# Astro Starter Kit: Component
+
+```
+npm init astro -- --template component
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/component)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro project, you'll see the following folders and files:
+
+```
+/
+├── demo/
+│   ├── public/
+│   └── src/
+│       └── pages/
+│           └── index.astro
+└── packages/
+    └── my-component/
+        ├── index.js
+        └── package.json
+```
+
+This project uses **workspaces** to develop a single package, `@example/my-component`, from `packages/my-component`. It also includes a `demo` Astro site for testing and demonstrating the component.
+
+
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command           | Action                                       |
+|:----------------  |:-------------------------------------------- |
+| `npm install`     | Installs dependencies                        |
+| `npm run dev`     | Starts local dev server at `localhost:3000`  |
+| `npm run build`   | Build your production site to `./dist/`      |
+| `npm run preview` | Preview your build locally, before deploying |
+
+## 👀 Want to learn more?
+
+Feel free to check [our documentation](https://github.com/withastro/astro) or jump into our [Discord server](https://astro.build/chat).
diff --git a/examples/component/astro.config.mjs b/examples/component/astro.config.mjs
new file mode 100644
index 000000000..94846abde
--- /dev/null
+++ b/examples/component/astro.config.mjs
@@ -0,0 +1,13 @@
+// Full Astro Configuration API Documentation:
+// https://docs.astro.build/reference/configuration-reference
+
+// @type-check enabled!
+// VSCode and other TypeScript-enabled text editors will provide auto-completion,
+// helpful tooltips, and warnings if your exported object is invalid.
+// You can disable this by removing "@ts-check" and `@type` comments below.
+
+// @ts-check
+export default /** @type {import('astro').AstroUserConfig} */ ({
+  // Comment out "renderers: []" to enable Astro's default component support.
+  renderers: [],
+});
diff --git a/examples/component/demo/package.json b/examples/component/demo/package.json
new file mode 100644
index 000000000..575002652
--- /dev/null
+++ b/examples/component/demo/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@example/my-component-demo",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "devDependencies": {
+    "astro": "^0.21.11"
+  }
+}
diff --git a/examples/component/demo/public/favicon.ico b/examples/component/demo/public/favicon.ico
new file mode 100644
index 000000000..578ad458b
--- /dev/null
+++ b/examples/component/demo/public/favicon.ico
diff --git a/examples/component/demo/public/robots.txt b/examples/component/demo/public/robots.txt
new file mode 100644
index 000000000..1f53798bb
--- /dev/null
+++ b/examples/component/demo/public/robots.txt
@@ -0,0 +1,2 @@
+User-agent: *
+Disallow: /
diff --git a/examples/component/demo/src/pages/index.astro b/examples/component/demo/src/pages/index.astro
new file mode 100644
index 000000000..96ca814e3
--- /dev/null
+++ b/examples/component/demo/src/pages/index.astro
@@ -0,0 +1,29 @@
+---
+import * as Component from '@example/my-component'
+---
+<html lang="en">
+
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width" />
+	<title>Welcome to Astro</title>
+	<style global>
+	h {
+		display: block;
+		font-size: 2em;
+		font-weight: bold;
+		margin-block: 0.67em;
+	}
+	</style>
+</head>
+
+<body>
+	<Component.Heading>
+		Welcome to Astro
+	</Component.Heading>
+	<Component.Button>
+		Plain Button
+	</Component.Button>
+</body>
+
+</html>
\ No newline at end of file
diff --git a/examples/component/package.json b/examples/component/package.json
new file mode 100644
index 000000000..84fe15ec4
--- /dev/null
+++ b/examples/component/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@example/component",
+  "version": "0.0.1",
+  "private": true,
+  "workspaces": [
+    "demo",
+    "packages/*"
+  ],
+  "scripts": {
+    "start": "astro --project-root demo dev",
+    "build": "astro --project-root demo build",
+    "serve": "astro --project-root demo preview"
+  },
+  "devDependencies": {
+    "astro": "^0.21.11"
+  }
+}
diff --git a/examples/component/packages/my-component/Button.astro b/examples/component/packages/my-component/Button.astro
new file mode 100644
index 000000000..d853628a1
--- /dev/null
+++ b/examples/component/packages/my-component/Button.astro
@@ -0,0 +1,15 @@
+---
+export interface Props extends Record<any, any> {
+	type?: string
+}
+
+const {
+	type,
+	...props
+} = {
+	...Astro.props
+} as Props
+
+props.type = type || 'button'
+---
+<button {...props}><slot /></button>
\ No newline at end of file
diff --git a/examples/component/packages/my-component/Heading.astro b/examples/component/packages/my-component/Heading.astro
new file mode 100644
index 000000000..f27e74b3d
--- /dev/null
+++ b/examples/component/packages/my-component/Heading.astro
@@ -0,0 +1,18 @@
+---
+export interface Props extends Record<any, any> {
+	level?: number | string
+	role?: string
+}
+
+const {
+	level,
+	role,
+	...props
+} = {
+	...Astro.props
+} as Props
+
+props.role = role || 'heading'
+props['aria-level'] = level || '1'
+---
+<h {...props}><slot /></h>
\ No newline at end of file
diff --git a/examples/component/packages/my-component/README.md b/examples/component/packages/my-component/README.md
new file mode 100644
index 000000000..41a53a6f0
--- /dev/null
+++ b/examples/component/packages/my-component/README.md
@@ -0,0 +1,37 @@
+# Example `@example/my-component`
+
+This is an example package, exported as `@example/my-component`. It consists of two Astro components, **Button** and **Heading**.
+
+### Button
+
+The **Button** component generates a `<button>` with a default **type** of **button**.
+
+```astro
+---
+import * as Component from '@example/my-component'
+---
+<Component.Button>Plain Button</Component.Button>
+```
+
+```html
+<!-- generated html -->
+<button type="button">Plain Button</button>
+```
+
+### Heading
+
+The **Heading** component generates an `<h>` tag with a default **role** of **heading** and a **level** attribute that gets written to **aria-level**.
+
+```astro
+---
+import * as Component from '@example/my-component'
+---
+<Component.Heading>Heading</Component.Heading>
+<Component.Heading level="2">Subheading</Component.Heading>
+```
+
+```html
+<!-- generated html -->
+<h role="heading" aria-level="1">Plain Button</h>
+<h role="heading" aria-level="2">Subheading</h>
+```
diff --git a/examples/component/packages/my-component/index.js b/examples/component/packages/my-component/index.js
new file mode 100644
index 000000000..603a81a96
--- /dev/null
+++ b/examples/component/packages/my-component/index.js
@@ -0,0 +1,2 @@
+export { default as Button } from './Button.astro';
+export { default as Heading } from './Heading.astro';
diff --git a/examples/component/packages/my-component/package.json b/examples/component/packages/my-component/package.json
new file mode 100644
index 000000000..47212b558
--- /dev/null
+++ b/examples/component/packages/my-component/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@example/my-component",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./Button": "./Button.astro",
+    "./Heading": "./Heading.astro"
+  },
+  "files": [
+    "index.js",
+    "Button.astro",
+    "Heading.jsx"
+  ],
+  "keywords": [
+    "astro-component",
+    "button",
+    "heading",
+    "example"
+  ]
+}
diff --git a/examples/component/sandbox.config.json b/examples/component/sandbox.config.json
new file mode 100644
index 000000000..9178af77d
--- /dev/null
+++ b/examples/component/sandbox.config.json
@@ -0,0 +1,11 @@
+{
+  "infiniteLoopProtection": true,
+  "hardReloadOnChange": false,
+  "view": "browser",
+  "template": "node",
+  "container": {
+    "port": 3000,
+    "startScript": "start",
+    "node": "14"
+  }
+}