px-icon: initial commit

2026-08-08 15:47:25 +02:00
commit c6035b66bf
5 changed files with 561 additions and 0 deletions
@@ -0,0 +1,66 @@
+# px-icon
+
+A tiny, dependency-free `<px-icon>` custom element that rasterizes an inline
+`<svg>` onto a shared art-pixel grid. The source `<svg>` stays untouched in
+light DOM (so server-driven morphs, e.g. Idiomorph/Datastar, can freely
+update it); the raster is rendered into shadow DOM.
+
+No build step, no npm, no dependencies. It's one ES module: `px-icon.js`.
+
+## Usage
+
+Serve `px-icon.js` from wherever you host static files (your CDN, gitea raw
+URL, whatever) and import it as a module:
+
+```html
+<script type="module" src="https://your-cdn.example/px-icon/v1.0.0/px-icon.js"></script>
+
+<px-icon>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+    <path fill="#4a90d9" d="M12 2 2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/>
+  </svg>
+</px-icon>
+```
+
+Or import it directly in your own module and let bundling/copying be
+someone else's problem:
+
+```html
+<script type="module">
+  import 'https://your-cdn.example/px-icon/v1.0.0/px-icon.js';
+</script>
+```
+
+### Config
+
+Set via CSS custom properties, so they cascade normally:
+
+| Property               | Default   | Values                    |
+|-------------------------|-----------|----------------------------|
+| `--pxicon-ap-size`       | `8` (px)  | art-pixel grid cell size   |
+| `--pxicon-mode`          | `average` | `average` \| `point`       |
+| `--pxicon-debug-delay`   | `0` (ms)  | artificial render delay, for testing progressive enhancement |
+
+```css
+:root {
+  --pxicon-ap-size: 6px;
+  --pxicon-mode: point;
+}
+```
+
+## Demo
+
+See [`examples/index.html`](examples/index.html) — open it directly in a
+browser (served over http, not `file://`, since it uses ES modules and
+`Blob` URLs) or point your dev server at the repo root.
+
+## Versioning
+
+No package.json, no registry. Releases are plain git tags (`v1.0.0`, ...)
+on the file as it exists at that commit. Point your CDN/proxy at a tag
+(or commit SHA) for a pinned, immutable URL; point at `main` only if you
+want to live dangerously.
+
+## License
+
+MIT, see [LICENSE](LICENSE).