Connection type (#81)

* Use union string instead of enum for easier consumption * Update docs with TypeScript note * Improve readme * Add very important missing semicolon * Make docs site more like GitHub readme
manifoldco · Apr 19, 2019 · 824a01f · 824a01f
1 parent 25edd03
commit 824a01f
Show file tree

Hide file tree

Showing 22 changed files with 187 additions and 119 deletions.
diff --git a/readme.md b/readme.md
@@ -1,42 +1,95 @@
 [![version (scoped)](https://img.shields.io/npm/v/@manifoldco/ui.svg)](https://www.npmjs.com/package/@manifoldco/ui)
+[![Stencil version](https://img.shields.io/badge/Stencil-v0.18.0-blueviolet.svg)](https://stenciljs.com)
 [![codecov](https://codecov.io/gh/manifoldco/ui/branch/master/graph/badge.svg?token=wDhQnzqKXR)](https://codecov.io/gh/manifoldco/ui)
 
-# @manifoldco/ui
+# 🍱 Manifold UI
 
-Manifold’s reusable web components, built with [Stencil][stencil]
+Manifold’s reusable web components, built with [Stencil][stencil].
 
 ## Installation
 
-Distribution is via npm. To use, run the following in any terminal:
-
 ```bash
-npm install @manifoldco/ui --save
+npm i @manifoldco/ui
 ```
 
-### Usage in Frameworks
+### Usage
+
+| Framework                 | Supported? |
+| :------------------------ | :--------: |
+| Vanilla JS (no framework) |     ✅     |
+| Angular                   |     ✅     |
+| React                     |     ✅     |
+| Vue                       |     ✅     |
+| Ember                     |     ✅     |
+
+#### HTML (ES Modules)
 
-Currently, Manifold UI supports the following frameworks:
+```html
+<manifold-marketplace />
 
-| Name                      | Supported? |
-| :------------------------ | :--------- |
-| Angular                   | ✅         |
-| React                     | ✅         |
-| Vue                       | ✅         |
-| Ember                     | ✅         |
-| Vanilla JS (no framework) | ✅         |
+<script type="module">
+  import { defineCustomElements } from 'https://unpkg.com/@manifoldco/ui/dist/esm/es2017/manifold.define.js';
+  defineCustomElements(window);
+</script>
+```
+
+#### HTML (No ESM Support)
 
-To integrate into your app, please refer to [Stencil’s documentation][stencil-framework].
+```html
+<manifold-marketplace />
+<script src="https://unpkg.com/@manifoldco/ui/dist/manifold.js"></script>
+```
 
-The only change needed from their docs is replace `test-components` with
-`@manifoldco/ui`, like so:
+#### React
 
-```js
-// Replace this… 🚫
-import { defineCustomElements } from 'test-components/dist/loader';
+```ts
+import React from 'react';
+import ReactDOM from 'react-dom';
 
-// …with this ✅
 import { defineCustomElements } from '@manifoldco/ui/dist/loader';
+
+const App = () => <manifold-marketplace />;
+
+ReactDOM.render(<App />, document.getElementById('root'));
+defineCustomElements(window);
+```
+
+#### Ember, Angular, Vue, and others
+
+Initializing Manifold UI works the exact same as any other Stencil project. For more
+advanced instructions on integrating with your specific stack, please refer
+to Stencil’s [docs on integration][stencil-framework].
+
+### TypeScript + JSX setup
+
+When using inside TypeScript, you’ll likely see this error (
+`manifold-connection` could be any custom element):
+
 ```
+Property 'manifold-connection' does not exist on type 'JSX.IntrinsicElements'
+```
+
+To solve that, add the following to `tsconfig.json`:
+
+```json
+"compilerOptions": {
+  "typeRoots": ["./node_modules/@types", "./node_modules/@manifoldco"],
+  "types": ["ui"]
+}
+```
+
+Next, create a `custom-elements.d.ts` file somewhere inside your project
+(must be inside the [include][ts-include] option in `tsconfig.json`):
+
+```ts
+declare module JSX {
+  interface IntrinsicElements extends StencilIntrinsicElements {}
+}
+```
+
+This will do more than fix the error—now you’ll be able to typecheck the web
+components as you write! 🎉
 
 [stencil]: https://stenciljs.com/
 [stencil-framework]: https://stenciljs.com/docs/overview
+[ts-include]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
diff --git a/src/components.d.ts b/src/components.d.ts
@@ -10,7 +10,6 @@ import '@stencil/core';
 import '@stencil/state-tunnel';
 import {
   Connection,
-  Env,
 } from './utils/connections';
 import {
   UserFeatures,
@@ -44,13 +43,13 @@ export namespace Components {
     /**
     * _(optional)_ Specify `env="stage"` for staging
     */
-    'env': Env;
+    'env': 'stage' | 'prod';
   }
   interface ManifoldConnectionAttributes extends StencilHTMLAttributes {
     /**
     * _(optional)_ Specify `env="stage"` for staging
     */
-    'env'?: Env;
+    'env'?: 'stage' | 'prod';
   }
 
   interface ManifoldCostDisplay {

diff --git a/src/components/manifold-connection/manifold-connection.tsx b/src/components/manifold-connection/manifold-connection.tsx
@@ -1,12 +1,12 @@
 import { Component, Prop } from '@stencil/core';
 
 import Tunnel from '../../data/connection';
-import { Env, connections } from '../../utils/connections';
+import { connections } from '../../utils/connections';
 
 @Component({ tag: 'manifold-connection' })
 export class ManiTunnel {
   /** _(optional)_ Specify `env="stage"` for staging */
-  @Prop() env: Env = Env.Prod;
+  @Prop() env: 'stage' | 'prod' = 'prod';
 
   render() {
     return (

diff --git a/src/components/manifold-connection/readme.md b/src/components/manifold-connection/readme.md
@@ -30,9 +30,9 @@ If you omit the `env` property, `manifold-connection` will point to production b
 
 ## Properties
 
-| Property | Attribute | Description                                    | Type                    | Default    |
-| -------- | --------- | ---------------------------------------------- | ----------------------- | ---------- |
-| `env`    | `env`     | _(optional)_ Specify `env="stage"` for staging | `Env.Prod \| Env.Stage` | `Env.Prod` |
+| Property | Attribute | Description                                    | Type                | Default  |
+| -------- | --------- | ---------------------------------------------- | ------------------- | -------- |
+| `env`    | `env`     | _(optional)_ Specify `env="stage"` for staging | `"prod" \| "stage"` | `'prod'` |
 
 
 ----------------------------------------------

diff --git a/src/components/manifold-data-product-logo/manifold-data-product-logo.tsx b/src/components/manifold-data-product-logo/manifold-data-product-logo.tsx
@@ -2,7 +2,7 @@
 import { Component, Prop, State, Element } from '@stencil/core';
 import Tunnel from '../../data/connection';
 import { withAuth } from '../../utils/auth';
-import { Connection, connections, Env } from '../../utils/connections';
+import { Connection, connections } from '../../utils/connections';
 
 @Component({ tag: 'manifold-data-product-logo' })
 
@@ -11,7 +11,7 @@ export class ManifoldDataProductLogo {
   /** _(optional)_ `alt` attribute */
   @Prop() alt?: string;
   /** _(hidden)_ Passed by `<manifold-connection>` */
-  @Prop() connection: Connection = connections[Env.Prod]; // Provided by manifold-connection
+  @Prop() connection: Connection = connections.prod; // Provided by manifold-connection
   /** URL-friendly slug (e.g. `"jawsdb-mysql"`) */
   @Prop() productLabel: string;
   @State() product?: Catalog.ExpandedProduct;

diff --git a/src/components/manifold-data-product-logo/readme.md b/src/components/manifold-data-product-logo/readme.md
@@ -33,11 +33,11 @@ This data component supports an optional loading state by specifying a child slo
 
 ## Properties
 
-| Property       | Attribute       | Description                                  | Type                  | Default                 |
-| -------------- | --------------- | -------------------------------------------- | --------------------- | ----------------------- |
-| `alt`          | `alt`           | _(optional)_ `alt` attribute                 | `string \| undefined` | `undefined`             |
-| `connection`   | --              | _(hidden)_ Passed by `<manifold-connection>` | `Connection`          | `connections[Env.Prod]` |
-| `productLabel` | `product-label` | URL-friendly slug (e.g. `"jawsdb-mysql"`)    | `string`              | `undefined`             |
+| Property       | Attribute       | Description                                  | Type                  | Default            |
+| -------------- | --------------- | -------------------------------------------- | --------------------- | ------------------ |
+| `alt`          | `alt`           | _(optional)_ `alt` attribute                 | `string \| undefined` | `undefined`        |
+| `connection`   | --              | _(hidden)_ Passed by `<manifold-connection>` | `Connection`          | `connections.prod` |
+| `productLabel` | `product-label` | URL-friendly slug (e.g. `"jawsdb-mysql"`)    | `string`              | `undefined`        |
 
 
 ----------------------------------------------

diff --git a/src/components/manifold-data-product-name/manifold-data-product-name.tsx b/src/components/manifold-data-product-name/manifold-data-product-name.tsx
@@ -2,14 +2,14 @@
 import { Component, Prop, State, Element } from '@stencil/core';
 import Tunnel from '../../data/connection';
 import { withAuth } from '../../utils/auth';
-import { Connection, connections, Env } from '../../utils/connections';
+import { Connection, connections } from '../../utils/connections';
 
 @Component({ tag: 'manifold-data-product-name' })
 
 export class ManifoldDataProductName {
   @Element() el: HTMLElement;
   /** _(hidden)_ Passed by `<manifold-connection>` */
-  @Prop() connection: Connection = connections[Env.Prod]; // Provided by manifold-connection
+  @Prop() connection: Connection = connections.prod; // Provided by manifold-connection
   /** URL-friendly slug (e.g. `"jawsdb-mysql"`) */
   @Prop() productLabel: string;
   @State() product?: Catalog.ExpandedProduct;

diff --git a/src/components/manifold-data-product-name/readme.md b/src/components/manifold-data-product-name/readme.md
@@ -30,10 +30,10 @@ The loading slot supports text as well as HTML elements.
 
 ## Properties
 
-| Property       | Attribute       | Description                                  | Type         | Default                 |
-| -------------- | --------------- | -------------------------------------------- | ------------ | ----------------------- |
-| `connection`   | --              | _(hidden)_ Passed by `<manifold-connection>` | `Connection` | `connections[Env.Prod]` |
-| `productLabel` | `product-label` | URL-friendly slug (e.g. `"jawsdb-mysql"`)    | `string`     | `undefined`             |
+| Property       | Attribute       | Description                                  | Type         | Default            |
+| -------------- | --------------- | -------------------------------------------- | ------------ | ------------------ |
+| `connection`   | --              | _(hidden)_ Passed by `<manifold-connection>` | `Connection` | `connections.prod` |
+| `productLabel` | `product-label` | URL-friendly slug (e.g. `"jawsdb-mysql"`)    | `string`     | `undefined`        |
 
 
 ----------------------------------------------

diff --git a/src/components/manifold-marketplace/manifold-marketplace.tsx b/src/components/manifold-marketplace/manifold-marketplace.tsx
@@ -2,13 +2,13 @@ import { Component, Prop, State, Element } from '@stencil/core';
 
 import Tunnel from '../../data/connection';
 import { withAuth } from '../../utils/auth';
-import { Connection, connections, Env } from '../../utils/connections';
+import { Connection, connections } from '../../utils/connections';
 
 @Component({ tag: 'manifold-marketplace' })
 export class ManifoldMarketplace {
   @Element() el: HTMLElement;
   /** _(hidden)_ Passed by `<manifold-connection>` */
-  @Prop() connection: Connection = connections[Env.Prod];
+  @Prop() connection: Connection = connections.prod;
   /** _(optional)_ Link format structure, with `:product` placeholder */
   @Prop() linkFormat?: string;
   /** _(optional)_ Comma-separated list of featured products (labels) */

diff --git a/src/components/manifold-marketplace/readme.md b/src/components/manifold-marketplace/readme.md
@@ -50,11 +50,11 @@ render() {
 
 ## Properties
 
-| Property     | Attribute     | Description                                                     | Type                  | Default                 |
-| ------------ | ------------- | --------------------------------------------------------------- | --------------------- | ----------------------- |
-| `connection` | --            | _(hidden)_ Passed by `<manifold-connection>`                    | `Connection`          | `connections[Env.Prod]` |
-| `featured`   | `featured`    | _(optional)_ Comma-separated list of featured products (labels) | `string \| undefined` | `undefined`             |
-| `linkFormat` | `link-format` | _(optional)_ Link format structure, with `:product` placeholder | `string \| undefined` | `undefined`             |
+| Property     | Attribute     | Description                                                     | Type                  | Default            |
+| ------------ | ------------- | --------------------------------------------------------------- | --------------------- | ------------------ |
+| `connection` | --            | _(hidden)_ Passed by `<manifold-connection>`                    | `Connection`          | `connections.prod` |
+| `featured`   | `featured`    | _(optional)_ Comma-separated list of featured products (labels) | `string \| undefined` | `undefined`        |
+| `linkFormat` | `link-format` | _(optional)_ Link format structure, with `:product` placeholder | `string \| undefined` | `undefined`        |
 
 
 ----------------------------------------------

diff --git a/src/components/manifold-plan-cost/manifold-plan-cost.tsx b/src/components/manifold-plan-cost/manifold-plan-cost.tsx
@@ -1,7 +1,7 @@
 import { Component, Element, Prop, State, Watch } from '@stencil/core';
 import { UserFeatures } from 'types/UserFeatures';
 import Tunnel from '../../data/connection';
-import { Connection, connections, Env } from '../../utils/connections';
+import { Connection, connections } from '../../utils/connections';
 import {
   planCost,
   hasMeasurableFeatures,
@@ -13,7 +13,7 @@ import {
 @Component({ tag: 'manifold-plan-cost' })
 export class ManifoldPlanCost {
   @Element() el: HTMLElement;
-  @Prop() connection: Connection = connections[Env.Prod];
+  @Prop() connection: Connection = connections.prod;
   @Prop() allFeatures: Catalog.ExpandedFeature[] = [];
   @Prop() compact?: boolean = false;
   @Prop() customizable?: boolean = false;

diff --git a/src/components/manifold-plan-cost/readme.md b/src/components/manifold-plan-cost/readme.md
@@ -22,14 +22,14 @@ one additional prop:
 
 ## Properties
 
-| Property           | Attribute      | Description | Type                   | Default                 |
-| ------------------ | -------------- | ----------- | ---------------------- | ----------------------- |
-| `allFeatures`      | --             |             | `ExpandedFeature[]`    | `[]`                    |
-| `compact`          | `compact`      |             | `boolean \| undefined` | `false`                 |
-| `connection`       | --             |             | `Connection`           | `connections[Env.Prod]` |
-| `customizable`     | `customizable` |             | `boolean \| undefined` | `false`                 |
-| `planId`           | `plan-id`      |             | `string`               | `undefined`             |
-| `selectedFeatures` | --             |             | `UserFeatures`         | `{}`                    |
+| Property           | Attribute      | Description | Type                   | Default            |
+| ------------------ | -------------- | ----------- | ---------------------- | ------------------ |
+| `allFeatures`      | --             |             | `ExpandedFeature[]`    | `[]`               |
+| `compact`          | `compact`      |             | `boolean \| undefined` | `false`            |
+| `connection`       | --             |             | `Connection`           | `connections.prod` |
+| `customizable`     | `customizable` |             | `boolean \| undefined` | `false`            |
+| `planId`           | `plan-id`      |             | `string`               | `undefined`        |
+| `selectedFeatures` | --             |             | `UserFeatures`         | `{}`               |
 
 
 ----------------------------------------------

diff --git a/src/components/manifold-plan-selector/manifold-plan-selector.tsx b/src/components/manifold-plan-selector/manifold-plan-selector.tsx
@@ -2,7 +2,7 @@ import { Component, State, Prop, Element } from '@stencil/core';
 
 import Tunnel from '../../data/connection';
 import { withAuth } from '../../utils/auth';
-import { Connection, connections, Env } from '../../utils/connections';
+import { Connection, connections } from '../../utils/connections';
 
 @Component({
   tag: 'manifold-plan-selector',
@@ -11,7 +11,7 @@ import { Connection, connections, Env } from '../../utils/connections';
 export class ManifoldPlanSelector {
   @Element() el: HTMLElement;
   /** _(hidden)_ Passed by `<manifold-connection>` */
-  @Prop() connection: Connection = connections[Env.Prod];
+  @Prop() connection: Connection = connections.prod;
   /** _(optional)_ Hide CTA? */
   @Prop() hideCta?: boolean;
   /** _(optional)_ Link format structure, with `:product`, `:plan`, and `:features` placeholders */

diff --git a/src/components/manifold-plan-selector/readme.md b/src/components/manifold-plan-selector/readme.md
@@ -66,13 +66,13 @@ If you would like to hide the CTA altogether, specify `hide-cta`:
 
 ## Properties
 
-| Property       | Attribute       | Description                                                                                | Type                   | Default                 |
-| -------------- | --------------- | ------------------------------------------------------------------------------------------ | ---------------------- | ----------------------- |
-| `connection`   | --              | _(hidden)_ Passed by `<manifold-connection>`                                               | `Connection`           | `connections[Env.Prod]` |
-| `hideCta`      | `hide-cta`      | _(optional)_ Hide CTA?                                                                     | `boolean \| undefined` | `undefined`             |
-| `linkFormat`   | `link-format`   | _(optional)_ Link format structure, with `:product`, `:plan`, and `:features` placeholders | `string \| undefined`  | `undefined`             |
-| `productLabel` | `product-label` | URL-friendly slug (e.g. `"jawsdb-mysql"`)                                                  | `string`               | `undefined`             |
-| `resourceId`   | `resource-id`   | _(optional)_ Is this modifying an existing resource?                                       | `string \| undefined`  | `undefined`             |
+| Property       | Attribute       | Description                                                                                | Type                   | Default            |
+| -------------- | --------------- | ------------------------------------------------------------------------------------------ | ---------------------- | ------------------ |
+| `connection`   | --              | _(hidden)_ Passed by `<manifold-connection>`                                               | `Connection`           | `connections.prod` |
+| `hideCta`      | `hide-cta`      | _(optional)_ Hide CTA?                                                                     | `boolean \| undefined` | `undefined`        |
+| `linkFormat`   | `link-format`   | _(optional)_ Link format structure, with `:product`, `:plan`, and `:features` placeholders | `string \| undefined`  | `undefined`        |
+| `productLabel` | `product-label` | URL-friendly slug (e.g. `"jawsdb-mysql"`)                                                  | `string`               | `undefined`        |
+| `resourceId`   | `resource-id`   | _(optional)_ Is this modifying an existing resource?                                       | `string \| undefined`  | `undefined`        |
 
 
 ----------------------------------------------

diff --git a/src/components/manifold-product/manifold-product.tsx b/src/components/manifold-product/manifold-product.tsx
@@ -2,13 +2,13 @@ import { Component, Prop, State, Element } from '@stencil/core';
 
 import Tunnel from '../../data/connection';
 import { withAuth } from '../../utils/auth';
-import { Connection, connections, Env } from '../../utils/connections';
+import { Connection, connections } from '../../utils/connections';
 
 @Component({ tag: 'manifold-product' })
 export class ManifoldProduct {
   @Element() el: HTMLElement;
   /** _(hidden)_ Passed by `<manifold-connection>` */
-  @Prop() connection: Connection = connections[Env.Prod];
+  @Prop() connection: Connection = connections.prod
   /** _(optional)_ Link format structure, with `:product` placeholder */
   @Prop() linkFormat?: string;
   /** URL-friendly slug (e.g. `"jawsdb-mysql"`) */