Merge pull request #8 from geneontology/basic-docs

Add basic usage docs in top-level readme

README.md

@@ -11,120 +11,75 @@ For the latest stable version of the GO web components, please visit:
 
 [![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 Component Starter
+# GO Web Components
 
-This is a starter project for building a standalone Web Component using Stencil.
+This repository contains a collection of web components produced by the Gene Ontology Consortium focusing on the display of GO Annotation data and GO-CAM models.
 
-Stencil is also great for building entire apps. For that, use the [stencil-app-starter](https://github.com/ionic-team/stencil-app-starter) instead.
+## Installation
 
-# Stencil
+These web components are framework-agnostic and designed to be integrated into any web application. The two main ways to install the components are via NPM or by using files served from a CDN.
 
-Stencil is a compiler for building fast web apps using Web Components.
+### NPM
 
-Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than runtime tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.
-
-Stencil components are just Web Components, so they work in any major framework or with no framework at all.
-
-## Getting Started
-
-To start building a new web component using Stencil, clone this repo to a new directory:
+To install the components via NPM, run the following command:
 
 ```bash
-git clone https://github.com/ionic-team/stencil-component-starter.git my-component
-cd my-component
-git remote rm origin
+npm install @geneontology/web-components
 ```
 
-and run:
+Once the package is installed, there are two ways to include the components in your application. The first method is to use the top-level lazy loader. Add this code near the beginning of your application code:
 
-```bash
-npm install
-npm start
+```javascript
+import "@geneontology/web-components";
 ```
 
-To build the component for production, run:
+This will allow you to use all custom elements provided by this package. The necessary code for each component is fetched on demand when it is first used.
 
-```bash
-npm run build
-```
+The second method is to import the individual component or components directly. For example, to use only `wc-go-ribbon` component:
 
-To run the unit tests for the components, run:
-
-```bash
-npm test
+```javascript
+import "@geneontology/web-components/wc-go-ribbon";
 ```
 
-Need help? Check out our docs [here](https://stenciljs.com/docs/my-first-component).
-
-## Naming Components
-
-When creating new component tags, we recommend _not_ using `stencil` in the component name (ex: `<stencil-datepicker>`). This is because the generated component has little to nothing to do with Stencil; it's just a web component!
-
-Instead, use a prefix that fits your company or any name for a group of related components. For example, all of the Ionic-generated web components use the prefix `ion`.
+In this case, no dynamic code fetching happens at runtime. This can lead to a more performant final application, but it requires you manage the imports for each component you use.
 
-## Using this component
+### CDN
 
-There are two strategies we recommend for using web components built with Stencil.
-
-The first step for all two of these strategies is to [publish to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages).
-
-You can read more about these different approaches in the [Stencil docs](https://stenciljs.com/docs/publishing).
-
-### Lazy Loading
-
-If your Stencil project is built with the [`dist`](https://stenciljs.com/docs/distribution) output target, you can import a small bootstrap script that registers all components and allows you to load individual component scripts lazily.
-
-For example, given your Stencil project namespace is called `my-design-system`, to use `my-component` on any website, inject this into your HTML:
+If your application does not use a build system or package manager, you can include the components directly from a CDN. Add the following script tag to your HTML file:
 
 ```html
-<script type="module" src="https://unpkg.com/my-design-system"></script>
-<!--
-To avoid unpkg.com redirects to the actual file, you can also directly import:
-https://unpkg.com/[email protected]/dist/foobar-design-system/foobar-design-system.esm.js
--->
-<my-component
-  first="Stencil"
-  middle="'Don't call me a framework'"
-  last="JS"
-></my-component>
+<script
+  type="module"
+  src="https://unpkg.com/@geneontology/web-components"
+></script>
 ```
 
-This will only load the necessary scripts needed to render `<my-component />`. Once more components of this package are used, they will automatically be loaded lazily.
+## Usage
 
-You can also import the script as part of your `node_modules` in your applications entry file:
+### `wc-go-ribbon`
 
-```tsx
-import "foobar-design-system/dist/foobar-design-system/foobar-design-system.esm.js";
-```
+The `wc-go-ribbon` component displays a ribbon of GO terms associated with one or more gene products.
 
-Check out this [Live Demo](https://stackblitz.com/edit/vitejs-vite-y6v26a?file=src%2Fmain.tsx).
+#### Example
 
-### Standalone
+```html
+<wc-go-ribbon subjects="RGD:620474,RGD:3889"></wc-go-ribbon>
+```
 
-If you are using a Stencil component library with `dist-custom-elements`, we recommend importing Stencil components individually in those files where they are needed.
+#### Documentation
 
-To export Stencil components as standalone components make sure you have the [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output target defined in your `stencil.config.ts`.
+https://github.com/geneontology/web-components/blob/main/src/components/go-ribbon/readme.md
 
-For example, given you'd like to use `<my-component />` as part of a React component, you can import the component directly via:
+### `wc-gocam-viz`
 
-```tsx
-import "foobar-design-system/my-component";
+The `wc-gocam-viz` component displays a GO-CAM model as a network diagram along with a list of processes and activities in the model.
 
-function App() {
-  return (
-    <>
-      <div>
-        <my-component
-          first="Stencil"
-          middle="'Don't call me a framework'"
-          last="JS"
-        ></my-component>
-      </div>
-    </>
-  );
-}
+#### Example
 
-export default App;
+```html
+<wc-gocam-viz gocam-id="635b1e3e00001811" show-legend="true"></wc-gocam-viz>
 ```
 
-Check out this [Live Demo](https://stackblitz.com/edit/vitejs-vite-b6zuds?file=src%2FApp.tsx).
+#### Documentation
+
+https://github.com/geneontology/web-components/blob/main/src/components/go-gocam-pathway/readme.md

package.json

@@ -3,6 +3,18 @@
   "version": "0.0.1",
   "description": "Web components for display of Gene Ontology annotations",
   "type": "module",
+  "author": {
+    "name": "The Gene Ontology Consortium",
+    "url": "https://geneontology.org",
+    "email": "[email protected]"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geneontology/web-components.git"
+  },
+  "bugs": {
+    "url": "https://github.com/geneontology/web-components/issues"
+  },
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",
   "types": "dist/types/index.d.ts",
@@ -11,19 +23,20 @@
   "unpkg": "dist/web-components/web-components.esm.js",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/web-components/web-components.esm.js",
-      "require": "./dist/web-components/web-components.cjs.js"
+      "require": "./dist/web-components/web-components.js"
+    },
+    "./*": {
+      "types": "./dist/components/*.d.ts",
+      "import": "./dist/components/*.js"
     },
     "./loader": {
+      "types": "./loader/index.d.ts",
       "import": "./loader/index.js",
-      "require": "./loader/index.cjs",
-      "types": "./loader/index.d.ts"
+      "require": "./loader/index.cjs"
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ionic-team/stencil-component-starter.git"
-  },
   "files": [
     "dist/",
     "loader/"

stencil.config.ts

@@ -21,6 +21,7 @@ import { sass } from "@stencil/sass";
 export const config: Config = {
   namespace: "web-components",
   plugins: [sass()],
+  buildEs5: "prod",
   outputTargets: [
     {
       type: "dist",
@@ -30,6 +31,7 @@ export const config: Config = {
       type: "dist-custom-elements",
       customElementsExportBehavior: "auto-define-custom-elements",
       externalRuntime: false,
+      generateTypeDeclarations: true,
     },
     {
       type: "docs-readme",