Update docs

DEVELOP.md

@@ -0,0 +1,101 @@
+![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)
+
+# Fourier Synthesizer Web Component
+
+This project is a standalone Web Component for generating waveforms and audio using Fourier synthesis. It is inspired from a [Java Applet](https://thole.org/manfred/fourier/en_idx.html) written by [Manfred Thole](https://thole.org/manfred/).
+<br></br>
+
+# Stencil
+
+[Stencil](https://stenciljs.com/docs/introduction) is a compiler for building Web Components. Fourier Synthesizer is built with Stencil on the Node.js platform using TypeScript, JSX, HTML, and SASS.
+
+For help with Stencil, see the Stencil [docs](https://stenciljs.com/docs/my-first-component).
+<br></br>
+
+# Use in another Node.js project
+
+```bash
+npm install fourier-synth
+```
+
+Visual Studio Code IntelliSense support is provided. Add the `vscode-docs.json` file included with the package under the VS Code setting for `html.customData` - for example `./node_modules/fourier-synth/vscode-docs.json`.
+<br></br>
+
+# Develop this project
+
+## Development stack
+
+This project is dependent on several development tools and technologies:
+
+1. Node.js
+2. NPM
+3. Git
+4. Stencil & Stencil SASS
+5. TypeScript
+6. JSX
+
+For a full list of project dependencies see [package.json](./package.json).
+
+## Development environment
+
+[Visual Studio Code](https://code.visualstudio.com/) is highly recommended as editor/IDE for this project. VS Code Configuration of many code features is included with the project along with recommended extensions.
+
+An [.editorconfig](https://editorconfig.org/) file is also provided for use with other editors but does not provide as many features as VS Code has.
+
+## Setup
+
+If you haven't already, you will need to install [Node.js](https://nodejs.org/) LTS v14 or newer (including NPM), and [Git](https://git-scm.com/). A terminal/shell environment is also required - Git Bash (which is included with Git for Windows) is recommended.
+
+To start development:
+
+Clone the project and install it:
+
+```bash
+git clone https://github.com/gtranter/fourier-synth.git
+cd fourier-synth
+npm install
+```
+
+Run the Stencil dev server:
+
+```bash
+npm start
+```
+
+## Build
+
+To build the component for production:
+
+```bash
+npm run build
+```
+
+## Test
+
+To run the unit tests for the component:
+
+```bash
+npm test
+```
+
+## Deploy
+
+To create the deployable archives:
+
+```bash
+npm run build.deployables
+```
+
+## APIs
+
+### Graphing
+
+Drawing of the Fourier waveforms graph is done using the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API).
+
+### Audio
+
+Sound generation is done using the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API).
+
+### Browser support
+
+`Firefox` (as of v112) and `Safari` (as of v16.3) do not support the disable normalization feature of the Web Audio API. As a result, the DC Offset control will not work properly - it is not possible to "clip" the generated wave where it exceeds the maximum level (the limits of the graph area). For best results use a different browser such as `Edge`, `Opera`, or another `Chromium` variant. For more information on browser support see the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/createPeriodicWave#browser_compatibility).

README.md

@@ -1,23 +1,47 @@
-# Fourier Synthesizer Web Component
+# [Fourier Synthesizer Web Component](https://github.com/gtranter/fourier-synth)
 
 This project is a standalone Web Component for generating waveforms and audio using Fourier synthesis.
 
 <img alt="fourier-synth" src="src/components/fourier-synth/fourier-synth.png" width="400" />
+<br></br>
 
-### Script import
+# Develop
 
-Add a script tag to the `<head>` section of your page. Remember to match the `/fourier-synth/` path shown below to that path on your server.
+For information about development using this project see [DEVELOP.md](./DEVELOP.md).
+<br></br>
+
+# Use on the web
+
+To use the Fourier Synthesizer web component on your web site, you need to import the component as a script and add the custom element tag to your page(s).
+
+## Browser support
+
+`Firefox` (as of v112) and `Safari` (as of v16.3) do not support the disable normalization feature of the Web Audio API. As a result, the DC Offset control will not work properly - it is not possible to "clip" the generated wave where it exceeds the maximum level (the limits of the graph area). For best results use a different browser such as `Edge`, `Opera`, or another `Chromium` variant. For more information on browser support see the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/createPeriodicWave#browser_compatibility).
+
+## Script import
+
+Add a script tag to the `<head>` section of your page. Replace `https://my.domain/server-path/fourier-synth/` shown below with the path where the component files are stored on your server or elsewhere.
+```html
+<script type="module" src="https://my.domain/server-path/fourier-synth/fourier-synth.esm.js"></script>
+```
+
+### Hosting
+
+Download one of the deploy files [[email protected]](./deploy/[email protected]) or [[email protected]](./deploy/[email protected]), and extract the contents. (The tgz file contains a tar file that needs to be extracted.) The extracted `fourier-synth` folder should be copied to your server including all contents. The name of the folder is not important, but it must match the `src` value of your page's script tag, and the file names must not be altered.
+
+### Serving from unpkg.com
+If you don't need guaranteed availability, you can use the component from unpkg.com.
 ```html
-<script type="module" src="/fourier-synth/fourier-synth.esm.js"></script>
+<script type="module" src="https://unpkg.com/[email protected]/dist/fourier-synth/fourier-synth.esm.js"></script>
 ```
 
-### Element tag
+## Element tag
 
 Add the element somewhere on your web page. Remember to use style or layout to control the size of the component.
 ```html
-<fourier-synth>Please enable JavaScript to use Fourier Synthesizer</fourier-synth>
+<fourier-synth style="width: 850px;">Please enable JavaScript to use Fourier Synthesizer</fourier-synth>
 ```
 
-### Customization
+## Customization
 
-See the [readme file](./src/components/fourier-synth/readme.md) for the web component.
+To customize the features of the component or translate into another language, see the [readme file](./src/components/fourier-synth/readme.md) for the web component.

vscode-docs.json

@@ -0,0 +1,150 @@
+{
+  "version": 1.1,
+  "tags": [
+    {
+      "name": "fourier-synth",
+      "description": {
+        "kind": "markdown",
+        "value": "The Fourier Synthesizer web component is an interactive waveform and sound generator based on Fourier synthesis.\r\n\r\n## Layout\r\nThe size of the synthesizer will by default be as large as possible within the web page. You can use CSS width and height properties and/or page layout to control the size if necessary.\r\n```html\r\n<fourier-synth style=\"width: 800px;\"></fourier-synth>\r\n```"
+      },
+      "attributes": [
+        {
+          "name": "audio-label",
+          "description": "Text for the enable audio control label."
+        },
+        {
+          "name": "auto-adjust",
+          "description": "Automatically adjust the gain and DC offset (cos0) to match the wave.\r\nThis doubles computational effort and therefore impacts performance by ~50%."
+        },
+        {
+          "name": "auto-adjust-label",
+          "description": "Text for the auto adjust control label."
+        },
+        {
+          "name": "axes-color",
+          "description": "Color of graph background lines and dots. Use a CSS color value."
+        },
+        {
+          "name": "background-color",
+          "description": "Background color of graph. Use a CSS color value."
+        },
+        {
+          "name": "cos-prefix",
+          "description": "Text for the cosine control prefix."
+        },
+        {
+          "name": "cos-title",
+          "description": "Title text for the cosine controls.  Set text empty to hide the title."
+        },
+        {
+          "name": "dc-label",
+          "description": "Text for the DC (cos0) control label. HTML can be used e.g. `A<sub>0</sub>`."
+        },
+        {
+          "name": "dividers-label",
+          "description": "Text for the dividers display control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "endpoints-label",
+          "description": "Text for the endpoints display control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "fundamental",
+          "description": "The fundamental frequency of the fourier wave."
+        },
+        {
+          "name": "fundamental-label",
+          "description": "Text for the fundamental control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "gain-label",
+          "description": "Text for the gain control label."
+        },
+        {
+          "name": "graph-label",
+          "description": "Text for the graph display control label."
+        },
+        {
+          "name": "grid-dots-label",
+          "description": "Text for the grid dots display control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "harmonics",
+          "description": "Number of harmonics to control and produce."
+        },
+        {
+          "name": "harmonics-label",
+          "description": "Text for the harmonics control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "hide-dividers",
+          "description": "Don't display the fundamental wave divider lines."
+        },
+        {
+          "name": "hide-endpoints",
+          "description": "Don't display the fundamental wave endpoint dots."
+        },
+        {
+          "name": "hide-graph",
+          "description": "Don't display the graph."
+        },
+        {
+          "name": "hide-grid-dots",
+          "description": "Don't display the graph background dots."
+        },
+        {
+          "name": "hide-offset",
+          "description": "Don't display the graph DC offset line."
+        },
+        {
+          "name": "line-color",
+          "description": "Color of the waveform plot line. Use a CSS color value."
+        },
+        {
+          "name": "line-width",
+          "description": "The width of the waveform plot line."
+        },
+        {
+          "name": "line-width-label",
+          "description": "Text for the line width control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "main-title",
+          "description": "Text for the main title. Set the text empty to hide the title."
+        },
+        {
+          "name": "max-harmonics",
+          "description": "Limit of the number of harmonics. The actual highest possible number of harmonics\r\nis based on the frequency. The highest possible harmonic frequency is 20000Hz. At\r\nthe lowest fundamental 20Hz there can therefore be up to 1000 harmonics. High values\r\ncan crash, hang, or otherwise bring the browser to a halt. USE WITH CAUTION."
+        },
+        {
+          "name": "offset-color",
+          "description": "Color of the graph DC offset line and waveform endpoint dots. Use a CSS color value."
+        },
+        {
+          "name": "offset-label",
+          "description": "Text for the offset display control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "periods",
+          "description": "Number of fundamental wave periods to display in the graph. From 1 to 5."
+        },
+        {
+          "name": "periods-label",
+          "description": "Text for the periods control label. Set the text empty to hide the control."
+        },
+        {
+          "name": "reset-text",
+          "description": "Text for the reset button."
+        },
+        {
+          "name": "sin-prefix",
+          "description": "Text for the sine control prefix."
+        },
+        {
+          "name": "sin-title",
+          "description": "Title text for the sine controls. Set text empty to hide the title."
+        }
+      ]
+    }
+  ]
+}