chore(example): add an example project

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"
+  ]
+}