@phun-ky/speccer 9.6.1 → 10.0.0

package/README.md

@@ -2,31 +2,36 @@
 
 ![Speccer hero, with logo and slogan: A zero dependency package to highlight elements](./public/speccer-hero.png)
 
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](http://makeapullrequest.com) [![SemVer 2.0](https://img.shields.io/badge/SemVer-2.0-green.svg)](http://semver.org/spec/v2.0.0.html) ![npm version](https://img.shields.io/npm/v/@phun-ky/speccer) ![issues](https://img.shields.io/github/issues/phun-ky/speccer) ![license](https://img.shields.io/npm/l/@phun-ky/speccer) ![size](https://img.shields.io/bundlephobia/min/@phun-ky/speccer) ![npm](https://img.shields.io/npm/dm/%40phun-ky/speccer) ![GitHub Repo stars](https://img.shields.io/github/stars/phun-ky/speccer) [![codecov](https://codecov.io/gh/phun-ky/speccer/graph/badge.svg?token=VA91DL7ZLZ)](https://codecov.io/gh/phun-ky/speccer)
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](http://makeapullrequest.com) [![SemVer 2.0](https://img.shields.io/badge/SemVer-2.0-green.svg)](http://semver.org/spec/v2.0.0.html) ![npm version](https://img.shields.io/npm/v/@phun-ky/speccer) ![issues](https://img.shields.io/github/issues/phun-ky/speccer) ![license](https://img.shields.io/npm/l/@phun-ky/speccer) ![size](https://img.shields.io/bundlephobia/min/@phun-ky/speccer) ![npm](https://img.shields.io/npm/dm/%40phun-ky/speccer) ![GitHub Repo stars](https://img.shields.io/github/stars/phun-ky/speccer) [![codecov](https://codecov.io/gh/phun-ky/speccer/graph/badge.svg?token=VA91DL7ZLZ)](https://codecov.io/gh/phun-ky/speccer) [![build](https://github.com/phun-ky/speccer/actions/workflows/check.yml/badge.svg)](https://github.com/phun-ky/speccer/actions/workflows/check.yml)
+
+## About
 
 ![Image of speccer](./public/speccer.png)
 
+**SPECCER** was originally created to simplify documenting components in a design system, but it can be used to highlight any HTML element on a webpage. If you need to draw attention to elements, **SPECCER** is your tool!
+
+## Table of Contents<!-- omit from toc -->
+
 - [@phun-ky/speccer](#phun-kyspeccer)
   - [About](#about)
   - [Installation](#installation)
-  - [API](#api)
   - [Usage](#usage)
     - [Typescript](#typescript)
     - [ESM](#esm)
+      - [Lazy loading](#lazy-loading)
     - [Script](#script)
+      - [Advanced usage](#advanced-usage)
     - [React](#react)
-  - [Advanced usage](#advanced-usage)
-    - [Lazy](#lazy)
   - [Features](#features)
     - [Element spacing](#element-spacing)
     - [Element dimensions](#element-dimensions)
       - [Subtle measure](#subtle-measure)
-    - [Highlight the anatomy of an element](#highlight-the-anatomy-of-an-element)
+    - [Pin element to highlight the anatomy](#pin-element-to-highlight-the-anatomy)
       - [Align with parent container](#align-with-parent-container)
       - [Custom literals](#custom-literals)
       - [Subtle anatomy](#subtle-anatomy)
       - [Curly brackets](#curly-brackets)
-      - [Highlight anatomy programatically](#highlight-anatomy-programatically)
+      - [Pin programatically](#pin-programatically)
     - [Element typography](#element-typography)
       - [Syntax highlighting for typography](#syntax-highlighting-for-typography)
     - [Grid spacing](#grid-spacing)
@@ -35,14 +40,15 @@
       - [Tab stops](#tab-stops)
       - [Landmarks and regions](#landmarks-and-regions)
       - [Keys and shortcut](#keys-and-shortcut)
-  - [Customization](#customization)
+    - [Customization](#customization)
+  - [API](#api)
+  - [Development](#development)
   - [Contributing](#contributing)
+  - [License](#license)
+  - [Changelog](#changelog)
+  - [FAQ](#faq)
   - [Sponsor me](#sponsor-me)
 
-## About
-
-**SPECCER** was originally created to simplify documenting components in a design system, but it can be used to highlight any HTML element on a webpage. If you need to draw attention to elements, **SPECCER** is your tool!
-
 ## Installation
 
 ```shell-session
@@ -51,10 +57,6 @@ npm i --save @phun-ky/speccer
 
 [See a live demo](https://codepen.io/phun-ky/pen/OJejexN).
 
-## API
-
-Full API documentation is available [here](https://github.com/phun-ky/speccer/blob/main/api/README.md).
-
 ## Usage
 
 ### Typescript
@@ -73,6 +75,45 @@ import speccer from '@phun-ky/speccer';
 speccer();
 ```
 
+#### Lazy loading
+
+If you're importing speccer instead of with a script tag, [you can use the following approach](https://codepen.io/phun-ky/pen/VwRRLyY) to apply lazy loading:
+
+```javascript
+import { pinElements } from "https://esm.sh/@phun-ky/speccer";
+
+/**
+ * Callback function for IntersectionObserver
+ * @param {IntersectionObserverEntry[]} entries - Array of entries being observed
+ * @param {IntersectionObserver} observer - The IntersectionObserver instance
+ * @returns {Promise<void>} Promise that resolves when element dissection is complete
+ */
+const intersectionCallback: IntersectionObserverCallback = async (entries, observer) => {
+  entries.forEach(async (entry) => {
+    if (entry.intersectionRatio > 0) {
+      await pinElements(entry.target);
+      observer.unobserve(entry.target);
+    }
+  });
+};
+
+// Creating IntersectionObserver instance with the callback
+const pinElementObserver = new IntersectionObserver(intersectionCallback);
+
+/**
+ * Function to observe elements using IntersectionObserver
+ * @param {Element} el - The element to be observed
+ */
+const observeElement = (el: Element): void => {
+  pinElementObserver.observe(el);
+};
+
+// Observing elements with the specified data attribute
+document.querySelectorAll('[data-speccer="pin-area"]').forEach((el) => {
+  observeElement(el);
+});
+```
+
 ### Script
 
 Or place these `script` and `link` tags in your web page:
@@ -94,6 +135,29 @@ Or with a CDN:
 
 And then follow the steps below to display the specifications you want :)
 
+#### Advanced usage
+
+If you want to control speccer a bit more, you have some options. Apply one of these attributes to the script element for different types of initialization:
+
+```html
+<script src="../speccer.js" data-<manual|instant|dom|lazy></script>
+```
+
+Or with a CDN:
+
+```html
+<script src="https://unpkg.com/@phun-ky/speccer/dist/speccer.js" data-<manual|instant|dom|lazy></script>
+```
+
+| Tag            | Description                                                         |
+| -------------- | ------------------------------------------------------------------- |
+| `data-manual`  | Makes `window.speccer()` available to be used when you feel like it |
+| `data-instant` | fires off `speccer()` right away                                    |
+| `data-dom`     | Waits for `DOMContentLoaded`                                        |
+| `data-lazy`    | Lazy loads `speccer()` per specced element                          |
+
+If no attribute is applied, it will default to `data-dom`, as in, it will initialize when `DOMContentLoaded` is fired.
+
 ### React
 
 If you use React, you can use an effect like this:
@@ -129,77 +193,6 @@ const Component = () => {
 export default Component;
 ```
 
-## Advanced usage
-
-If you want to control speccer a bit more, you have some options. Apply one of these attributes to the script element for different types of initialization:
-
-```html
-<script src="../speccer.js" data-<manual|instant|dom|lazy></script>
-```
-
-Or with a CDN:
-
-```html
-<script src="https://unpkg.com/@phun-ky/speccer/dist/speccer.js" data-<manual|instant|dom|lazy></script>
-```
-
-| Tag            | Description                                                         |
-| -------------- | ------------------------------------------------------------------- |
-| `data-manual`  | Makes `window.speccer()` available to be used when you feel like it |
-| `data-instant` | fires off `speccer()` right away                                    |
-| `data-dom`     | Waits for `DOMContentLoaded`                                        |
-| `data-lazy`    | Lazy loads `speccer()` per specced element                          |
-
-If no attribute is applied, it will default to `data-dom`, as in, it will initialize when `DOMContentLoaded` is fired.
-
-### Lazy
-
-If you're importing speccer instead of with a script tag, [you can use the following approach](https://codepen.io/phun-ky/pen/VwRRLyY) to apply lazy loading:
-
-```javascript
-import { dissect, ElementDissectionResult } from "https://esm.sh/@phun-ky/speccer";
-
-/**
- * Function to dissect an HTML element
- * @param {Element} target - The element to be dissected
- * @returns {Promise<ElementDissectionResult>} Promise that resolves with the dissection result
- */
-const dissectElement = (target: Element): Promise<ElementDissectionResult> => {
-  return dissect.element(target);
-};
-
-/**
- * Callback function for IntersectionObserver
- * @param {IntersectionObserverEntry[]} entries - Array of entries being observed
- * @param {IntersectionObserver} observer - The IntersectionObserver instance
- * @returns {Promise<void>} Promise that resolves when element dissection is complete
- */
-const intersectionCallback: IntersectionObserverCallback = async (entries, observer) => {
-  entries.forEach(async (entry) => {
-    if (entry.intersectionRatio > 0) {
-      await dissectElement(entry.target);
-      observer.unobserve(entry.target);
-    }
-  });
-};
-
-// Creating IntersectionObserver instance with the callback
-const dissectElementObserver = new IntersectionObserver(intersectionCallback);
-
-/**
- * Function to observe elements using IntersectionObserver
- * @param {Element} el - The element to be observed
- */
-const observeElement = (el: Element): void => {
-  dissectElementObserver.observe(el);
-};
-
-// Observing elements with the specified data attribute
-document.querySelectorAll('[data-anatomy-section]').forEach((el) => {
-  observeElement(el);
-});
-```
-
 ## Features
 
 ### Element spacing
@@ -209,7 +202,7 @@ document.querySelectorAll('[data-anatomy-section]').forEach((el) => {
 Use the following attribute to display element padding and margin:
 
 ```html
-<div data-speccer class="..."></div>
+<div data-speccer="spacing" class="..."></div>
 ```
 
 This will display the element _and all of it's children_ padding and margin.
@@ -222,7 +215,7 @@ Display dimensions with:
 
 ```html
 <div
-  data-speccer-measure="[height right|left] | [width top|bottom]"
+  data-speccer="measure [height right|left] | [width top|bottom]"
   class="..."
 ></div>
 ```
@@ -236,21 +229,21 @@ Where `height` and `width` comes with placement flags. Default for `height` is `
 Use a subtle style:
 
 ```html
-<div data-speccer-measure="height left subtle" class="..."></div>
+<div data-speccer="measure height left subtle" class="..."></div>
 ```
 
 This will give a dashed border.
 
-### Highlight the anatomy of an element
+### Pin element to highlight the anatomy
 
 ![Image of speccer](./public/anatomy.png)
 
-In your component examples, use the following attribute. Remember to use the `data-anatomy-section` as an attribute on a parent element to scope the marking.
+In your component examples, use the following attribute. Remember to use the `data-speccer="pin-area"`-attribute on a parent element to scope the marking.
 
 ```html
-<div data-anatomy-section>
+<div data-speccer="pin-area">
   <div
-    data-anatomy="outline [full|enclose][curly] [left|right|top|bottom]"
+    data-speccer="pin [bracket|enclose][curly] [left|right|top|bottom]"
     class="..."
   ></div>
 </div>
@@ -265,13 +258,13 @@ This will place a pin to the outline of the element. Default is `top`.
 You can also align the pins to the parent container.
 
 ```html
-<div data-anatomy-section>
-  <div data-anatomy="outline parent [left|right|top|bottom]" class="..."></div>
+<div data-speccer="pin-area">
+  <div data-speccer="pin parent [left|right|top|bottom]" class="..."></div>
 </div>
 ```
 
 > [!NOTE]  
-> Only works with `outline [left|right|top|bottom]`, and not with `enclose`, `full` or `curly`!
+> Only works with `pin [left|right|top|bottom]`, and not with `enclose`, `bracket` or `curly`!
 
 The lines from the element to the pin is drawn with a svg path and circle, so remember to add the following svg into your document:
 
@@ -319,8 +312,8 @@ window.SPECCER_LITERALS = [
 You can also give a more subtle touch to the anatomy elements.
 
 ```html
-<div data-anatomy-section>
-  <div data-anatomy="outline top subtle" class="..."></div>
+<div data-speccer="pin-area">
+  <div data-speccer="pin top subtle" class="..."></div>
 </div>
 ```
 
@@ -328,10 +321,10 @@ This will give a dashed border, and a more subtle pin style.
 
 #### Curly brackets
 
-You can use curly brackets with the `curly` tag in `data-anatomy` along side `outline full` to provide a more sleek style.
+You can use curly brackets with the `curly` tag in `data-speccer` along side `pin bracket` to provide a more sleek style.
 
 > [!NOTE]  
-> Only works with `outline full`
+> Only works with `pin bracket`
 
 The curly brackets are made with SVG paths, and it is required to have the following snippet on your page for it to render:
 
@@ -352,9 +345,9 @@ The curly brackets are made with SVG paths, and it is required to have the follo
 </svg>
 ```
 
-#### Highlight anatomy programatically
+#### Pin programatically
 
-from v9.5 you can utilize the `dissect` feature to highlight the anatomy of an element programaticaly. [Here is an example with a click event](https://codepen.io/phun-ky/full/LYKOWyP).
+from v9.5 you can utilize the `pin` feature to highlight the anatomy of an element programaticaly. [Here is an example with a click event](https://codepen.io/phun-ky/bracket/LYKOWyP).
 
 [Kazam_screencast_00002.webm](https://github.com/user-attachments/assets/5c78cece-de46-4876-81f2-98c9108a2103)
 
@@ -365,7 +358,7 @@ from v9.5 you can utilize the `dissect` feature to highlight the anatomy of an e
 Display typography details:
 
 ```html
-<p data-speccer-typography="[left|right|top|bottom]" class="...">Some text</p>
+<p data-speccer="typography [left|right|top|bottom]" class="...">Some text</p>
 ```
 
 This will place a box to display typography information. Default is `left`.
@@ -375,12 +368,10 @@ This will place a box to display typography information. Default is `left`.
 
 #### Syntax highlighting for typography
 
-If you want to produce a box that uses `pre` and `code` tags with support for syntax highlighting ([PrismJS](https://prismjs.com/) compatible), add `syntax` to the `data-speccer-typography` attribute.
+If you want to produce a box that uses `pre` and `code` tags with support for syntax highlighting ([PrismJS](https://prismjs.com/) compatible), add `syntax` to the `data-speccer="typography"` attribute.
 
 ```html
-<p data-speccer-typography="[left|right|top|bottom][syntax]" class="...">
-  Some text
-</p>
+<p data-speccer="typography syntax right" class="...">Some text</p>
 ```
 
 You can then override the colors, based on these variables:
@@ -430,7 +421,7 @@ This will highlight the grid spacing in a `display: grid;` element.
 In your component examples, use the following attribute on your grid container.
 
 ```html
-<div data-speccer-grid="grid" …>…</div>
+<div data-speccer="grid" …>…</div>
 ```
 
 ### Mark elements
@@ -442,7 +433,7 @@ This will mark the given elements.
 In your component examples, use the following attribute.
 
 ```html
-<div data-speccer-mark …>…</div>
+<div data-speccer="mark" …>…</div>
 ```
 
 ### A11y notation
@@ -455,25 +446,31 @@ Prior art: [Jeremy Elder](https://twitter.com/JeremyElder)
 
 ![Screenshot of speccer a11y tab stops in use](./public/a11y-tabstop.png)
 
-If you want to display tab stops, append `data-speccer-a11y-tabstops` as an attribute to the container you want to display the tab stops in.
+If you want to display tab stops, append `data-speccer="a11y tabstops"` as an attribute to the container you want to display the tab stops in.
 
 #### Landmarks and regions
 
 ![Screenshot of speccer a11y landmarks in use](./public/a11y-landmark.png)
 
-If you want to display landmarks and regions, append `data-speccer-a11y-landmark` as an attribute to the container you want to display the landmarks and regions in.
+If you want to display landmarks and regions, append `data-speccer="a11y landmark"` as an attribute to the container you want to display the landmarks and regions in.
 
 #### Keys and shortcut
 
 ![Screenshot of speccer a11y shortcuts in use](./public/a11y-shortcut.png)
 
-If you want to display the shortcut with keys used for elements, use `data-speccer-a11y-shortcut="<shortcut>"` on the element that uses this shortcut:
+If you want to display the shortcut with keys used for elements, use `data-speccer="a11y shortcut"` and `data-speccer-a11y-shortcut="<shortcut>"` on the element that uses this shortcut:
 
 ```html
-<button type="button" data-speccer-a11y-shortcut="ctrl + s">Save</button>
+<button
+  type="button"
+  data-speccer="a11y shortcut"
+  data-speccer-a11y-shortcut="ctrl + s"
+>
+  Save
+</button>
 ```
 
-## Customization
+### Customization
 
 ![Screenshot of speccer in a dark mode example](./public/darkmode.png)
 
@@ -481,38 +478,94 @@ Allthough the styling works nicely with dark mode, you can use the provided CSS
 
 ```css
 .ph-speccer.speccer {
-  --ph-speccer-color-padding: rgba(219, 111, 255, 0.4);
-  --ph-speccer-color-padding-hover: #db6fff;
-  --ph-speccer-color-margin: rgba(255, 247, 111, 0.4);
-  --ph-speccer-color-margin-hover: #fff76f;
-  --ph-speccer-color-text-light: #fff;
-  --ph-speccer-color-text-dark: #333;
-  --ph-speccer-color-contrast: #ff3aa8;
-  --ph-speccer-spacing-color: var(--ph-speccer-color-contrast);
-  --ph-speccer-measure-color: #f00;
-  --ph-speccer-pin-color: var(--ph-speccer-color-contrast);
-  --ph-speccer-typography-background-color: #fff;
-  --ph-speccer-typography-color-property: #3f85f2;
-  --ph-speccer-typography-color-text: #57575b;
-  --ph-speccer-typography-color-value: var(--ph-speccer-color-contrast);
-  --ph-speccer-depth-opacity-400: 0.4;
-  --ph-speccer-font-family: 'Menlo for Powerline', 'Menlo Regular for Powerline',
-    'DejaVu Sans Mono', Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono',
-    monospace;
-  --ph-speccer-font-size: 12px;
-  --ph-speccer-line-height: 12px;
+  --ph-speccer-color-artificialStrawberry: #ff3aa8;
+  --ph-speccer-color-venusSlipperOrchid: #db6fff;
+  --ph-speccer-color-superBanana: #fff76f;
+  --ph-speccer-color-white: #ffffff;
+  --ph-speccer-color-carbon: #333333;
+  --ph-speccer-color-red: #ff0000;
+  --ph-speccer-color-niuZaiSeDenim: #0074e8;
+  --ph-speccer-color-beautifulBlue: #1868b2;
+  --ph-speccer-color-fuchsiaBlue: #7e60c5;
+  --ph-speccer-base-color: var(--ph-speccer-color-artificialStrawberry);
+  --ph-speccer-spacing-color: var(--ph-speccer-base-color);
+  --ph-speccer-spacing-color-padding: rgb(
+    from var(--ph-speccer-color-venusSlipperOrchid) r g b /
+      var(--ph-speccer-opacity-40)
+  );
+  --ph-speccer-spacing-color-padding-hover: var(
+    --ph-speccer-color-venusSlipperOrchid
+  );
+  --ph-speccer-spacing-color-margin: rgb(
+    from var(--ph-speccer-color-superBanana) r g b /
+      var(--ph-speccer-opacity-40)
+  );
+  --ph-speccer-spacing-color-margin-hover: var(--ph-speccer-color-superBanana);
+  --ph-speccer-typography-background-color: var(--ph-speccer-color-white);
+  --ph-speccer-typography-color-property: var(--ph-speccer-color-niuZaiSeDenim);
+  --ph-speccer-typography-color-text: var(--ph-speccer-base-color);
+  --ph-speccer-typography-color-value: var(--ph-speccer-base-color);
+  --ph-speccer-mark-background-color: rgb(
+    from var(--ph-speccer-base-color) r g b / var(--ph-speccer-opacity-20)
+  );
+  --ph-speccer-mark-border-color: var(--ph-speccer-base-color);
+  --ph-speccer-mark-border-width: 1px;
+  --ph-speccer-mark-border-style: solid;
+  --ph-speccer-measure-color: var(--ph-speccer-color-red);
+  --ph-speccer-measure-size: 8px;
+  --ph-speccer-a11y-color-bakground: var(--ph-speccer-color-beautifulBlue);
+  --ph-speccer-a11y-landmark-color-background: var(
+    --ph-speccer-color-fuchsiaBlue
+  );
+  --ph-speccer-color-text-light: var(--ph-speccer-color-white);
+  --ph-speccer-color-text-dark: var(--ph-speccer-color-carbon);
+  --ph-speccer-pin-color: var(--ph-speccer-base-color);
   --ph-speccer-pin-size: 24px;
   --ph-speccer-pin-space: 48px;
+  --ph-speccer-line-height: 12px;
   --ph-speccer-line-width: 1px;
   --ph-speccer-line-width-negative: -1px;
-  --ph-speccer-measure-size: 8px;
+  --ph-speccer-opacity-20: 0.2;
+  --ph-speccer-opacity-40: 0.4;
+  --ph-speccer-font-family: 'Menlo for Powerline', 'Menlo Regular for Powerline',
+    'DejaVu Sans Mono', Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono',
+    monospace;
+  --ph-speccer-font-size: 12px;
+  --ph-speccer-transition-default: all 2s cubic-bezier(0.4, 0, 0.2, 1);
 }
 ```
 
+## API
+
+Full API documentation is available [here](https://github.com/phun-ky/speccer/blob/main/api/README.md).
+
+## Development
+
+```
+// Build
+$ npm run build
+// Run dev
+$ npm run dev
+// Test
+$ npm test
+```
+
 ## Contributing
 
 Want to contribute? Please read the [CONTRIBUTING.md](https://github.com/phun-ky/speccer/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/phun-ky/speccer/blob/main/CODE_OF_CONDUCT.md)
 
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/phun-ky/speccer/blob/main/LICENSE) file for details.
+
+## Changelog
+
+See the [CHANGELOG.md](https://github.com/phun-ky/speccer/blob/main/CHANGELOG.md) for details on the latest updates.
+
+## FAQ
+
+See the [discussions](https://github.com/phun-ky/speccer/discussions/categories/q-a) for an FAQ or to ask questions if no answer is given.
+
 ## Sponsor me
 
 I'm an Open Source evangelist, creating stuff that does not exist yet to help get rid of secondary activities and to enhance systems already in place, be it documentation or web sites.
@@ -522,3 +575,5 @@ The sponsorship is an unique opportunity to alleviate more hours for me to maint
 [Support me on GitHub Sponsors](https://github.com/sponsors/phun-ky).
 
 ![Speccer banner, with logo and slogan: A zero dependency package to highlight elements](./public/speccer-banner.png)
+
+p.s. **Ukraine is still under brutal Russian invasion. A lot of Ukrainian people are hurt, without shelter and need help**. You can help in various ways, for instance, directly helping refugees, spreading awareness, putting pressure on your local government or companies. You can also support Ukraine by donating e.g. to [Red Cross](https://www.icrc.org/en/donate/ukraine), [Ukraine humanitarian organisation](https://savelife.in.ua/en/donate-en/#donate-army-card-weekly) or [donate Ambulances for Ukraine](https://www.gofundme.com/f/help-to-save-the-lives-of-civilians-in-a-war-zone).