DRAFT: new components diff, mgc demo locally running

.editorconfig

@@ -0,0 +1,29 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+
+[*]
+
+# Change these settings to your own preference
+indent_style = space
+indent_size = 2
+
+# We recommend you to keep these unchanged
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.json]
+indent_size = 2
+
+[*.{html,js,md}]
+block_comment_start = /**
+block_comment = *
+block_comment_end = */

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: App CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Run tests
+      run: yarn run test
+
+    - name: Upload reports
+      run: npx codecov

.github/workflows/gh-pages-main.yml

@@ -0,0 +1,36 @@
+# This workflow will generate the static page under `main` subdirectory inside the `gh-pages` branch
+
+# This workflow will run every time new changes were pushed to the `main` branch
+
+name: App build CI/CD to main branch
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Create build files for gh-pages deploy
+        run: yarn ghpages:build
+
+      # Reference: https://github.com/JamesIves/github-pages-deploy-action
+      - name: Deploy 🚀
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: ghpages
+          clean-exclude: pr/
+          force: false
+          target-folder: main
+          token: ${{ secrets.GH_TOKEN }}

.github/workflows/pr-preview.yml

@@ -0,0 +1,35 @@
+# This workflow will generate the static page under `pr` subdirectory inside the `gh-pages` branch
+
+# This workflow will run every time there's a PR opened, reopened, synchronize, or closed
+
+name: Deploy PR previews
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install and Build
+        run: |
+          npm install
+          yarn ghpages:build
+
+      # Reference: https://github.com/rossjrw/pr-preview-action
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./ghpages/
+          umbrella-dir: pr

.gitignore

@@ -1,9 +1,30 @@
-packages/ia-prototype-apps/dist
-packages/ia-prototype-apps/.cache
-yarn-error.log
-node_modules
-jest-test-utils
-__snapshots__
-/publish_dev.sh
-/dist
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+!.vscode/tasks.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+## npm
+/node_modules/
+/npm-debug.log
+
+## temp folders
+/.tmp/
+
+# build
+/components/**/*.js
+/components/**/*.js.map
+/components/**/*.d.ts
+
+# Logs
+logs
 *.log
+npm-debug.log*
+npm-error.log*
+coverage

.prettierignore

@@ -0,0 +1 @@
+coverage

README.md

@@ -1,85 +1,167 @@
-![Build Status](https://github.com/internetarchive/iaux/actions/workflows/node.js.yml/badge.svg?branch=master) [![codecov](https://codecov.io/gh/internetarchive/iaux/branch/master/graph/badge.svg)](https://codecov.io/gh/internetarchive/iaux)
+![Build Status](https://github.com/internetarchive/iaux-typescript-wc-template/actions/workflows/ci.yml/badge.svg) [![codecov](https://codecov.io/gh/internetarchive/iaux-typescript-wc-template/graph/badge.svg?token=ZOYRJ2BV9W)](https://codecov.io/gh/internetarchive/iaux-typescript-wc-template)
 
-# Overview
+# Internet Archive Typescript WebComponent Template
 
-Here lies a few packages for UI components used on [Archive.org](https://archive.org).
+This is a base template for creating Typescript WebComponents. It is based off of the [Open WebComponents generator](https://open-wc.org/docs/development/generator/) with some IA-specific customizations and some development niceities.
 
-This repo is no longer open to receive new packages.  Please refer to https://github.com/internetarchive/iaux-typescript-wc-template when creating new components.
-## Setup
+## Usage
 
-EACH PACKAGE in `/packages` _MUST_ INSTALL ITS OWN DEPS.
+1. Click the "Use this Template" button in GitHub to create a new repository based on this one.
+2. Clone your new repo and update the things below:
 
-Note: we no longer use lerna to manage dependencies nor releases
+### Things to update in your copy
+1. Remove this section
+2. Search for the strings `your-webcomponent` and `YourWebComponent` and those are most of the spots that need to be updated.
+3. `README.md` (this file). Update the readme in general, but also the badge URLs
+4. `package.json` Update the name and description
+5. Rename the `your-webcomponent.ts` and its associated `.test` file
+6. Enable `Codecov` and `renovate` in the GitHub Apps section if not already enabled (be sure not to enable `pre-commit`)
+7. Set up a Codecov token (see [Codecov Setup](#codecov-setup))
 
+## Local Demo with `web-dev-server`
+Add `127.0.0.1 local.archive.org` to your `/etc/hosts` file
 
-### Running ia-components (only)
-Run our local UI component development environment.
-```
-cd packages/ia-components && yarn run storybook
+```bash
+npm run start
 ```
 
-## Code Structure
+**NOTE** The first time you visit the site, the browser will say the site is insecure because it's using a self-signed certificate. Accept the certificate and visit the site and the browser will then accept the certificate in the future. It may always say the site is insecure, but for the purposes of development, it's secure enough.
 
-There are several node packages in this one repo. They are located under the `packages` directory.
+To run a local development server that serves the basic demo located in `demo/index.html`
 
-## Publishing
+## Testing with Web Test Runner
+To run the suite of Web Test Runner tests, run
+```bash
+npm run test
+```
 
-EACH PACKAGE in `/packages` directory manages its own release.
+To run the tests in watch mode (for <abbr title="test driven development">TDD</abbr>, for example), run
 
-To clarify in the commit/merge, please note package & its new version. ex. [email protected]
+```bash
+npm run test:watch
+```
 
-## Coding rules
+## Releasing alpha and production tagged packages to NPM
+### Releasing alpha and test packages
+- Use your Jira ticket to create your namespace.  This will prevent collision as many people can be simultaneously working in the same repository.
+  - run: **`npm version prerelease --preid=wedev-1234`**
+    - this command will help auto-increment your alpha package tags inside your jira ticket namespace. refer to [npm versioning docs](https://docs.npmjs.com/cli/v11/commands/npm-version) & [guides for more info on command options](- this command will help auto-increment your alpha package tags inside your jira ticket namespace)
+  - run: **`npm publish --tag alpha`** our most used development tags are: alpha, canary
+
+### Releasing production level package
+We like to create a pull request specifically after the expected changes are merged into the main branch.
+Steps:
+- create PR with version number as branch name. Ex, if the next version is 3.2.1, your git command will be:  `git checkout -b v3.2.1`
+  - in the new branch, run the following:
+    1. **`git pull --tags`** to fetch all git tags
+    2. **`npm version X.X.X`** to set the new tag WITH the commit git tagged
+    3. **`git push --tags`**
+    4. **`npm publish`**
+- Note: version numbers must start at minimum, with 1 (1.x.x) in order for consumers to automatically receive patch updates (no tags starting with 0, like 0.x.x)
+
+## Linting with ESLint, Prettier, and Types
+To scan the project for linting errors, run
+```bash
+npm run lint
+```
 
-This is structured so that there is compatibility with the upstream Archive.org codebase.
+To automatically fix many linting errors, run
+```bash
+npm run format
+```
 
-#### JS Styleguide
-Currently, we are using [Airbnb's styleguide](https://github.com/airbnb/javascript) and will extend accordingly.
-We have added [ESLint](https://eslint.org) to help with staying in convention.
+## Tooling configs
 
-## Using StorybookJS
+For most of the tools, the configuration is in the `package.json` to reduce the amount of files in your project.
 
-Some packages use [StorybookJS](https://storybook.js.org) to show usage examples of our components.  For details on how to run StorybookJS, visit the `ia-components` readme: [IA Components Readme](/packages/ia-components/README.md)
+If you customize the configuration a lot, you can consider moving them to individual files.
 
-Run Storybook in ia-components:
-```
-cd packages/ia-components && yarn run storybook
-```
+### Codecov setup
+**Finding your token**
+- Log in at https://codecov.io/ with your GitHub account
+- Switch from your personal organization to `internetarchive` if needed, by toggling at the top of the screen or visiting https://app.codecov.io/gh/internetarchive directly
+- Find your repository and hit the `Configure` button or visit `https://app.codecov.io/gh/internetarchive/YOUR-REPO-NAME/config`
+- Go the `General` tab and find the `Tokens` section
+- Copy everything after `CODECOV_TOKEN=`
 
-## Unit Testing with JestJS
+**Adding your token**
+- Return to your repository and go to `Settings` > `Secrets and variables` (under `Security`) > `Actions`
+- Select `New repository secret`
+- Name your secret `CODECOV_TOKEN` and paste in the token you just copied
+- Select `Add Secret`
 
-[JestJS](https://jestjs.io) is pliable enough for us to test in JavaScript and TypeScript.
-Try running our tests:
-```
-cd packages/ia-components && yarn run test
-```
+**Adding your badge**
+- Back in `Configuration` in Codecov, go to the `Badges & Graphs` section
+- Copy the Markdown version of the badge
+- Delete the current Codecov badge at the top of this README and replace it with your new badge
 
-## Debugging
-We are using the common [debug module](https://www.npmjs.com/package/debug).
+## Steps to setup `gh-pages` static site generator
 
-To add to a module, add a line like
-```
-const debug = require('debug')('ia-components:COMPONENTNAME')
-```
-To enable, for example, debugging in all ia-components, and debugging in the dweb-archive:Nav module.
+Let's start with creating a `gh-pages` branch.
+
+This branch is where Github will look for the `index.html` to be hosted
 
-In Node add a line to your top level application BEFORE requiring or importing the other modules.
-```
-process.env.DEBUG="ia-components:* dweb-archive:Nav"
-```
-In Browser, add a line to your index.html or equivalent BEFORE including the bundle.
 ```
-<script type="text/javascript">localStorage.debug = "dweb-archive dweb-archive:* dweb-transports dweb-transports:* dweb-objects dweb-objects:*";</script>
+git checkout --orphan gh-pages
+git reset --hard
+git commit --allow-empty -m "Initializing gh-pages branch"
+git push origin gh-pages
 ```
 
+### Additional setup
 
-## Other
-
-in `v2mocks` there is code that is pulled from IA "View Source" and converted to JSX using this tool:
-`https://magic.reactjs.net/htmltojsx.htm`
+- Go to repo `Settings` -> sidebar `Pages`
+- In the `Source` drop-down, choose the branch where you want to host your Github Pages and the `directory` where it was hosted
+  - We'll use `gh-pages` branch for this but you can use other branch name for this
+  - Just make sure that's the branch where the `index.html` that you want to host lives in
 
+<p align="center">
+  <img src="screenshot/gh-pages-settings.png" alt="Github Pages Settings" style="height:720px; width:890px;">
+</p>
 
-Archive.org v2 uses [Bootstrap](https://getbootstrap.com) 3.0. Docs can be found here: http://bootstrapdocs.com/v3.0.0/docs/css/#overview
+## Manual Deploy using `gh-pages`
 
-## License
+You can update the current Github Page without pushing a commit by running:
+```
+npm run ghpages:publish
+```
 
-[See our license file.](/LICENSE.md)
+This build script does the following, see `package.json`:
+- `ghpages:publish`
+  - This executes `ghpages:prepare` in the current branch you are currently working on
+    - Note: The branch name is required so that it will not override the whole Github Pages directory
+  - You can check it by navigating through the branch name files directory you set from the [step to setup `gh-pages` branch](#steps-to-setup-gh-pages)
+    - You can checkout how it looks like in one of our projects here: [https://github.com/internetarchive/iaux-collection-browser/tree/gh-pages](https://github.com/internetarchive/iaux-collection-browser/tree/gh-pages)
+
+- `ghpages:prepare`
+  - This executes `ghpages:build` that builds the project dependencies and generates `vite` build from it
+  - We use [vite](https://vitejs.dev/) to bundle and generate the static assets that we host in Github Pages
+    - See `vite.config.ts` related to this
+
+- `ghpages:generate`
+  - This executes `gh-pages` [npm package](https://www.npmjs.com/package/gh-pages) command to publish/upload the generated files from our `vite` build files
+  - Upon executing this command:
+    - This generates a commit message formatted from the most recent commit message of the branch
+    - Push the commit to `gh-pages` branch that we setup earlier
+
+The live demo app URL from current branch will look something like this:
+`https://<organization_name_or_username>.github.io/<repo_name>/<branch_name>/demo`
+
+## Automatic Deploy of Demo App
+
+Things that trigger automatic site generation:
+- a merge to `main`
+  - See workflow: `gh-pages-main.yml`
+  - Example: `https://<organization_name_or_username>.github.io/<repo_name>/main`
+
+- a pull request against `main`
+  - See workflow: `pr-preview.yml`
+    - The URL for your Pull Request will be deleted after merging to main but you can update that in the config
+  - When you create a Pull Request, if your code passes codecov unit tests, it will be always served live at base URL/pull request number.
+  - Example: `https://<organization_name_or_username>.github.io/<repo_name>/pr/<pr-number>/demo`
+    - Note that `demo` is another directory where the `index.html` lives in
+    - You are free to playaround with it and set your desired file directory/structure on your end
+
+Another thing to note: pushing a branch up alone will not trigger site creation.
+
+Happy devving ^_^ 🥳  🎉