chore(example): add an example project (#2)

add a stencil-component-starter to the project to act as an example as to how the output target works. for the first pass here, we'll only demonstrate some props metadata being surfaced in an HTML file

CONTRIBUTING.md

@@ -46,7 +46,8 @@ Please see our [Contributor Code of Conduct](https://github.com/stencil-communit
 4. This repo uses [volta](https://volta.sh) to manage its npm and Node versions.
    [Install it](https://docs.volta.sh/guide/getting-started) before proceeding.
     1. There's no need to install a specific version of npm or Node right now, it shall be done automatically for you in the next step.
-5. Run `npm ci`
+5. Run `npm ci` to install dependencies
+6. Run `npm run build` to build the project
 
 ### Updates
 

example/.gitignore

@@ -0,0 +1,26 @@
+dist/
+www/
+loader/
+
+*~
+*.sw[mnpcod]
+*.log
+*.lock
+*.tmp
+*.tmp.*
+log.txt
+*.sublime-project
+*.sublime-workspace
+
+.stencil/
+.idea/
+.vscode/
+.sass-cache/
+.versions/
+node_modules/
+$RECYCLE.BIN/
+
+.DS_Store
+Thumbs.db
+UserInterfaceState.xcuserstate
+.env

example/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "example",
+  "version": "0.0.1",
+  "description": "Stencil Component Starter",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "collection": "dist/collection/collection-manifest.json",
+  "collection:main": "dist/collection/index.js",
+  "unpkg": "dist/example/example.esm.js",
+  "exports": {
+    ".": {
+      "import": "./dist/example/example.esm.js",
+      "require": "./dist/example/example.cjs.js"
+    },
+    "./my-component": {
+      "import": "./dist/components/my-component.js",
+      "types": "./dist/components/my-component.d.ts"
+    },
+    "./loader": {
+      "import": "./loader/index.js",
+      "require": "./loader/index.cjs",
+      "types": "./loader/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ionic-team/stencil-component-starter.git"
+  },
+  "files": [
+    "dist/",
+    "loader/"
+  ],
+  "scripts": {
+    "build": "stencil build",
+    "start": "stencil build --dev --watch --serve",
+    "test": "stencil test --spec --e2e",
+    "test.watch": "stencil test --spec --e2e --watchAll",
+    "generate": "stencil generate"
+  },
+  "devDependencies": {
+    "@stencil-community/web-types-output-target": "file:..",
+    "@stencil/core": "^4.7.0",
+    "@types/node": "^16.18.11"
+  },
+  "license": "MIT",
+  "web-types": "./web-types.json"
+}

example/readme.md

@@ -0,0 +1,37 @@
+[![Built With Stencil](https://img.shields.io/badge/-Built%20With%20Stencil-16161d.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCA1MTIgNTEyOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGRkZGRjt9Cjwvc3R5bGU%2BCjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00MjQuNywzNzMuOWMwLDM3LjYtNTUuMSw2OC42LTkyLjcsNjguNkgxODAuNGMtMzcuOSwwLTkyLjctMzAuNy05Mi43LTY4LjZ2LTMuNmgzMzYuOVYzNzMuOXoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTQyNC43LDI5Mi4xSDE4MC40Yy0zNy42LDAtOTIuNy0zMS05Mi43LTY4LjZ2LTMuNkgzMzJjMzcuNiwwLDkyLjcsMzEsOTIuNyw2OC42VjI5Mi4xeiIvPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDI0LjcsMTQxLjdIODcuN3YtMy42YzAtMzcuNiw1NC44LTY4LjYsOTIuNy02OC42SDMzMmMzNy45LDAsOTIuNywzMC43LDkyLjcsNjguNlYxNDEuN3oiLz4KPC9zdmc%2BCg%3D%3D&colorA=16161d&style=flat-square)](https://stenciljs.com)
+
+# `@stencil-community/web-types-output-target` Example Project
+
+This project demonstrates the usage of the `@stencil-community/web-types-output-target` output target.
+
+## Set Up
+
+To set up this project, you may either first build the output target from source, or override this project's dependency on `@stencil-community/web-types-output-target` with a version published to the NPM registry.
+Both allow you to take the output target for a 'test drive' - the only difference is the former allows you to tweak the output target's source code and see how it affects the example project.
+
+After setting up the dependencies, continue to the next section.
+
+### Building from Source
+
+See the [instructions in the CONTRIBUTING guide](https://github.com/stencil-community/stencil-web-types/blob/main/CONTRIBUTING.md#setup) to build from source.
+
+### Overriding the Local Dependency
+
+If you don't want to build the output target from source, run the following from this directory to install it from the NPM registry:
+```bash
+$ npm uninstall @stencil-community/web-types-output-target
+$ npm install --save-dev @stencil-community/web-types-output-target
+```
+
+## Inspecting Types
+
+To inspect the types of the components in this project, one must first build the project.
+This generates a `web-types.json` file, which JetBrains IDEs use to pick up metadata about the project's components.
+To build the project, run the following from this directory:
+
+```bash
+$ npm run build
+```
+
+Upon build, open the [example index.html file](./src/index.html) in your JetBrains IDE.
+Hover over components to see how JSDoc descriptions, deprecation tags, default and required values, etc. are now populated in the editor.

example/src/components.d.ts

@@ -0,0 +1,83 @@
+/* eslint-disable */
+/* tslint:disable */
+/**
+ * This is an autogenerated file created by the Stencil compiler.
+ * It contains typing information for all components that exist in this project.
+ */
+import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";
+export namespace Components {
+    /**
+     * A component for displaying a person's name
+     */
+    interface MyComponent {
+        /**
+          * The first name, which is required
+         */
+        "first": string;
+        /**
+          * The last name
+         */
+        "last": string;
+        /**
+          * The middle name, defaults to "Unknown"
+         */
+        "middle": string;
+        /**
+          * A suffix, for titles like "PhD" and "MBA"
+          * @deprecated
+         */
+        "suffix": string;
+    }
+}
+declare global {
+    /**
+     * A component for displaying a person's name
+     */
+    interface HTMLMyComponentElement extends Components.MyComponent, HTMLStencilElement {
+    }
+    var HTMLMyComponentElement: {
+        prototype: HTMLMyComponentElement;
+        new (): HTMLMyComponentElement;
+    };
+    interface HTMLElementTagNameMap {
+        "my-component": HTMLMyComponentElement;
+    }
+}
+declare namespace LocalJSX {
+    /**
+     * A component for displaying a person's name
+     */
+    interface MyComponent {
+        /**
+          * The first name, which is required
+         */
+        "first": string;
+        /**
+          * The last name
+         */
+        "last"?: string;
+        /**
+          * The middle name, defaults to "Unknown"
+         */
+        "middle"?: string;
+        /**
+          * A suffix, for titles like "PhD" and "MBA"
+          * @deprecated
+         */
+        "suffix"?: string;
+    }
+    interface IntrinsicElements {
+        "my-component": MyComponent;
+    }
+}
+export { LocalJSX as JSX };
+declare module "@stencil/core" {
+    export namespace JSX {
+        interface IntrinsicElements {
+            /**
+             * A component for displaying a person's name
+             */
+            "my-component": LocalJSX.MyComponent & JSXBase.HTMLAttributes<HTMLMyComponentElement>;
+        }
+    }
+}

example/src/components/my-component/my-component.css

@@ -0,0 +1,3 @@
+:host {
+  display: block;
+}

example/src/components/my-component/my-component.tsx

@@ -0,0 +1,36 @@
+import { Component, Prop, h } from '@stencil/core';
+
+/**
+ * A component for displaying a person's name
+ */
+@Component({
+  tag: 'my-component',
+  styleUrl: 'my-component.css',
+  shadow: true,
+})
+export class MyComponent {
+  /**
+   * The first name, which is required
+   */
+  @Prop() first!: string;
+
+  /**
+   * The middle name, defaults to "Unknown"
+   */
+  @Prop() middle: string = "Unknown";
+
+  /**
+   * The last name
+   */
+  @Prop() last: string;
+
+  /**
+   * A suffix, for titles like "PhD" and "MBA"
+   * @deprecated
+   */
+  @Prop() suffix: string;
+
+  render() {
+    return <div>Hello, World! I'm here</div>;
+  }
+}

example/src/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html dir="ltr" lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+    <title>Stencil Component Starter</title>
+
+    <script type="module" src="/build/example.esm.js"></script>
+    <script nomodule src="/build/example.js"></script>
+  </head>
+  <body>
+    <!-- See the repo's README for setup instructions -->
+    <!-- After setup, hover over the component name and each of the props -->
+    <!--
+         - my-component will have its description pulled from it's JSDoc
+         - first will have its description pulled from its JSDoc. Its required status will be reported.
+         - middle will have its description pulled from its JSDoc. Its default value will be reported.
+         - last will have its description pulled from its JSDoc.
+         - suffix will have its description pulled from its JSDoc. It will be reported as deprecated.
+    -->
+    <my-component first="Stencil" middle=" " last="'Don't call me a framework'" suffix="JS"></my-component>
+  </body>
+</html>

example/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview entry point for your component library
+ *
+ * This is the entry point for your component library. Use this file to export utilities,
+ * constants or data structure that accompany your components.
+ *
+ * DO NOT use this file to export your components. Instead, use the recommended approaches
+ * to consume components of this package as outlined in the `README.md`.
+ */
+
+export type * from './components.d.ts';

example/stencil.config.ts

@@ -0,0 +1,16 @@
+import { Config } from '@stencil/core';
+import { webTypesOutputTarget } from '@stencil-community/web-types-output-target';
+
+export const config: Config = {
+  namespace: 'example',
+  outputTargets: [
+    {
+      type: 'www',
+      serviceWorker: null, // disable service workers
+    },
+    webTypesOutputTarget(),
+  ],
+  testing: {
+    browserHeadless: "new",
+  },
+};

example/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "allowUnreachableCode": false,
+    "declaration": false,
+    "experimentalDecorators": true,
+    "lib": [
+      "dom",
+      "es2017"
+    ],
+    "moduleResolution": "node",
+    "module": "esnext",
+    "target": "es2017",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "jsx": "react",
+    "jsxFactory": "h"
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}