Updated readme documentation

Author: tim-harding

CONTRIBUTING.md

@@ -8,28 +8,39 @@ cd squircle
 npm install
 ```
 
-## Test
+## Library
 
-To serve a test page and watch for changes:
+To serve a test page:
 
 ```sh
-npm run serve
+npm run dev
 ```
 
-The test page is available at `http://localhost:8080`.
+To build the library for production:
 
-## Build
+```sh
+npm run build
+```
 
-To build the package into `./package`:
+To publish the library to NPM:
 
 ```sh
-npm run build
+./publish.sh
 ```
 
-## Publish
+### Publish
 
 ```sh
 cd package
 npm publish
 cd ..
 ```
+
+## GitHub Pages demo
+
+The GitHub Actions workflow automatically builds and deploys the site after
+pushing to `main`. To serve the website for local development, use
+
+```sh
+npm run pages-dev
+```

README.md

@@ -9,61 +9,101 @@ magic](https://tim-harding.github.io/squircle/).
 
 ### CSS
 
-First, initialize the library. Unlike most JavaScript, the worklet cannot be
-imported as a module, so the worklet file must be served at the provided URL.
-You can either use the minified files from [unpkg](https://unpkg.com/) or use
-your bundler to get a URL.
+First, register the squircle web worker. 
 
 ```js
-import url from "superellipse-squircle/worklet.min.js?url"; // Vite
-import url from "url:superellipse-squircle/worklet.min.js"; // Parcel & WMR
-import url from "omt:superellipse-squircle/worklet.min.js"; // Rollup
-import url from "url-loader!:superellipse-squircle/worklet.min.js"; // WebPack 4 & 5
-const url = "https://unpkg.com/[email protected]/worklet.min.js"; // unpkg
-
 import { register } from "superellipse-squircle";
-register(url);
+register();
+```
+
+Now you can use `paint(squircle)` as a image source in CSS. Usually that will be
+`background: paint(squircle);`, in which case you can use the provided
+`squircle` class. This includes a fallback to normal rounded rectangles when CSS
+Houdini isn't available. 
 
-import "superellipse-squircle/index.css"; // Optional
+```html
 <div
   class="squircle"
   style="
-    --squircle-radius: 1rem;
-    --squircle-fill: black;"
+    --squircle-border-radius: 1rem;
+    --squircle-background-color: black;"
 ></div>;
 ```
 
-Linking or importing the provided CSS creates a `squircle` class with fallbacks
-for unsupported browsers. Alternatively, use the image source directly in your
-CSS. For example, try `mask-image: paint(squircle);` to create a squircle layer
-mask. At time of writing, only Chromium-based browsers support the Paint API, so
-use `@supports (paint(id)) {...}` to check for support. See [Can I
-Use](https://caniuse.com/css-paint-api) for updates.
-
 These properties control the squircle drawing:
 
-| Property                  | Equivalent         |
-| ------------------------- | ------------------ |
-| `--squircle-radius`       | `border-radius`    |
-| `--squircle-fill`         | `background-color` |
-| `--squircle-border-width` | `border-width`     |
-| `--squircle-border-color` | `border-color`     |
+| Property                      | Equivalent         |
+| ----------------------------- | ------------------ |
+| `--squircle-background-color` | `background-color` |
+| `--squircle-border-radius`    | `border-radius`    |
+| `--squircle-border-width`     | `border-width`     |
+| `--squircle-border-color`     | `border-color`     |
 
-To reduce verbosity, consider aliasing the CSS properties. For example, to use
-`--radius` instead of `--squircle-radius`:
+To reduce the verbosity, consider using aliases:
 
 ```css
 .squircle {
-  --squircle-radius: var(--radius);
+  --squircle-background-color: var(--fill);
+  --squircle-border-radius: var(--radius);
+  --squircle-border-width: var(--border-width);
+  --squircle-border-color: var(--border-color);
 }
 ```
 
+### Web component
+
+The `squircle` class falls back to normal rounded rectangles on browsers that
+don't support the Paint API, which is [most of
+them](https://caniuse.com/css-paint-api) at time of writing. To guarantee
+squircles on all platforms, you can use the web component instead. It will add
+an HTML5 `<canvas>` to draw with when the Paint API isn't available.
+
+```js
+import { createCustomElement } from 'superellipse-squircle';
+createCustomElement();
+```
+
+```html
+<th-squircle
+  background-color="rgba(64, 128, 192, 0.5)"
+  border-radius="16"
+  border-width="4"
+  border-color="black"
+>
+  Hello, world!
+</th-squircle>
+```
+
 ### Canvas
 
 You can also use the squircle drawing code directly in an HTML canvas. Import
 the `paint` function to draw into a canvas context.
 
 ```js
-import { paint } from "superellipse-squircle";
-paint(canvasContext, posX, posY, width, height, borderRadius);
+import { draw, paint } from "superellipse-squircle";
+
+// Just create a path
+draw(canvasContext, posX, posY, width, height, borderRadius);
+
+// Draw the squircle with stroke and fill
+paint(canvasContext, posX, posY, width, height, borderRadius, 
+  borderWidth, fillColor, borderColor);
+```
+
+### SVG
+
+You can create a string that is compatible with SVG `path` elements. 
+
+```svg
+<svg viewBox="0 0 512 512">
+  <path id="my-path" />
+</svg>
+```
+
+```js
+import { path } from "superellipse-squircle";
+
+const d = path(0, 0, 512, 512, myRadius);
+const path = document.getElementById('my-path');
+path.d = d;
 ```

TODO.md

@@ -1,3 +1,4 @@
+- Use slots for Canvas web component
 - Update readme for API updates
 - Touch support for corners
 - Title gradient

src/index.js

@@ -11,40 +11,50 @@ export * from "./drawing.js";
  * @property {number} y y-coordinate
  */
 
+function registerInner() {
+  let isRegistered = false;
+  return function() {
+    if (isRegistered) return;
+    isRegistered = true;
+
+    const style = document.createElement("style");
+    style.textContent = styles;
+    document.head.append(style);
+
+    /* @ts-ignore */
+    if (!CSS.paintWorklet) return;
+    /* @ts-ignore */
+    CSS.paintWorklet.addModule(workletUrl);
+  }
+}
+
 /**
  * Register the squircle CSS Paint worklet.
  */
-export function register() {
-  const style = document.createElement("style");
-  style.textContent = styles;
-  document.head.append(style);
-
-  /* @ts-ignore */
-  if (!CSS.paintWorklet) return;
-  /* @ts-ignore */
-  CSS.paintWorklet.addModule(workletUrl);
-}
+export const register = registerInner()
 
 /**
  * Creates a custom element that uses the Paint API if available or an HTML
  * canvas if not.
  *
  * Usage:
  * ```js
+ * // No argument defaults to th-squircle
  * createCustomElement('my-squircle')
  * ```
  * ```html
  * <my-squircle
- *     radius="16"
- *     fill="#deadbeef"
+ *     background-color="#deadbeef"
+ *     border-radius="16"
  *     border-width="4"
  *     border-color="#cafebabe"
  * ></my-squircle>
  * ```
  *
- * @param {string} name
+ * @param {string} [name='th-squircle'] HTML element tag
  */
-export function createCustomElement(name) {
+export function createCustomElement(name = 'th-squircle') {
+  register()
   /* @ts-ignore */
   const isPaintSupported = !!CSS.paintWorklet;
   const component = isPaintSupported ? SquircleHoudini : SquircleCanvas;

tsconfig.json

@@ -17,8 +17,6 @@
     "isolatedModules": true,
     "strict": true,
     "allowJs": true,
-    "checkJs": true,
-    "declaration": true,
-    "emitDeclarationOnly": true
+    "checkJs": true
   }
 }