@zumer/orbit 2.0.0 → 2.1.0

package/README.md

@@ -11,7 +11,7 @@ Orbit puts HTML on circles. Gauges, dials, knobs, radial menus, donut charts, wa
 
 You write plain HTML with a few classes. CSS does the geometry and the look; a small runtime keeps numbering, spacing and SVG arcs right as things change. It works the same in plain HTML, React, Vue, Svelte or anything else that renders the DOM.
 
-[Documentation and examples](https://zumerlab.com/orbit/) · [npm](https://www.npmjs.com/package/@zumer/orbit) · [Orbit 1.x docs](https://zumerlab.com/orbit-docs/)
+[Documentation and examples](https://zumerlab.com/orbit/) · [npm](https://www.npmjs.com/package/@zumer/orbit)
 
 ## Install
 
@@ -156,16 +156,12 @@ Values cascade, so set them once on the `.gravity-spot` for the whole system or
 
 ### Which way is out
 
-Each satellite tells its content where it sits: `--o-dir-x` and `--o-dir-y` are the direction from the center, from `-1` to `1` (`y` grows down, and both are `0` on the center satellite). It is handy for labels that should hang outward, above the satellites of the upper half and below the rest:
+Each satellite tells its content where it sits: `--o-dir-x` and `--o-dir-y` are the direction from the center, from `-1` to `1` (`y` grows down, and both are `0` on the center satellite). Two classes use them for labels. On a capsule or inside one, `.outward` sets a label just outside its satellite along that direction, and `.outward-y` only above or below: above the satellites of the upper half, below the rest. `--o-outward-gap` (4px) is the space between them.
 
-```css
-.label {
-  /* -1 in the upper half, 1 in the lower half */
-  --side: clamp(-1, var(--o-dir-y) * 1000, 1);
-  position: absolute; left: 50%;
-  top: calc(50% + var(--side) * (50% + 4px));
-  translate: -50% calc((var(--side) - 1) * 50%);
-}
+```html
+<div class="satellite">
+  <div class="capsule"><span class="dot"></span><span class="outward-y">Mars</span></div>
+</div>
 ```
 
 ## Arcs and progress
@@ -190,7 +186,19 @@ Text inside an arc is drawn along it. With `range="auto"` the arc is as long as
 </div>
 ```
 
-Progress rings draw filled bands. For a thin gauge line, use `variant="stroke"`: a 2px line over a gray track, colored with `--o-stroke` and `--o-back-stroke`.
+`start` places an arc at a point of its ring, on the same scale as `value`. A placed arc takes no slot and moves no other arc, so labels and segments can go over a ring that already has arcs. `--o-max` on a ring or system sets the scale for everything below it, so values stay in their own units, hours for example:
+
+```html
+<div class="orbit-9" style="--o-max: 12; --o-from: 40deg; --o-range: 320deg">
+  <o-arc value="12" style="--o-fill: #222a33"></o-arc>
+  <o-arc start="1" value="2.5" style="--o-fill: #4fd1c5"></o-arc>
+  <o-arc range="auto" start="0" text-anchor="end" style="--o-fill: transparent">Lights</o-arc>
+</div>
+```
+
+`class="ripple"` sends waves out of an arc to call for attention; `--o-ripple-color`, `--o-ripple-duration` and `--o-ripple-scale` tune them.
+
+Progress rings draw filled bands. For a thin gauge line, use `variant="stroke"`: a 2px line over a gray track, colored with `--o-stroke` and `--o-back-stroke`. A `.satellite.at-value` in the same ring sits on the value of the progress and follows it, like the knob of a dial.
 
 Arcs and progress are decorative until you say otherwise. `interactive` makes the whole band clickable, transparent or not, and `hit-width="12"` adds 12px of touch area on each side:
 
@@ -294,7 +302,7 @@ Version 2 changes where size comes from. In 1.x every system was 500px across, w
 - `<o-arc>` and `<o-progress>` are placed with `rotate` instead of `transform`, and endings scale with the band. `interactive` makes the whole band clickable.
 - `variant="stroke"` on `<o-progress>` draws a 2px line over a gray track by default.
 
-The [1.x documentation](https://zumerlab.com/orbit-docs/) stays online.
+The 1.x source and README stay on GitHub, at the [v1.6.0 tag](https://github.com/zumerlab/orbit/tree/v1.6.0#readme).
 
 ## Demos
 

package/dist/custom-elements.json

@@ -25,7 +25,7 @@
             },
             {
               "name": "max",
-              "description": "Value that fills the ring's range. Must be positive.",
+              "description": "Value that fills the ring's range. Must be positive. Without it, --o-max of the ring or system.",
               "type": {
                 "text": "number"
               },
@@ -54,6 +54,13 @@
               },
               "default": "0"
             },
+            {
+              "name": "start",
+              "description": "Where the arc begins, on the same scale as value. A placed arc takes no slot and moves no other arc: text over a ring that already has arcs, or segments on a timeline.",
+              "type": {
+                "text": "number"
+              }
+            },
             {
               "name": "text-anchor",
               "description": "Where curved text sits on the arc. With range=\"auto\", an explicit value anchors the arc at its angle: middle centers it, end ends it there.",
@@ -104,6 +111,22 @@
             {
               "name": "--o-gap",
               "description": "Space between sibling arcs. Default 1; cascades from the ring or system."
+            },
+            {
+              "name": "--o-max",
+              "description": "Value that fills the range when there is no max attribute. Default 100; cascades from the ring or system."
+            },
+            {
+              "name": "--o-ripple-color",
+              "description": "Color of the .ripple wave. Default --o-fill."
+            },
+            {
+              "name": "--o-ripple-duration",
+              "description": "One wave of .ripple. Default 1.6s."
+            },
+            {
+              "name": "--o-ripple-scale",
+              "description": "How far a .ripple wave grows, from the center of the ring. Default 1.14."
             }
           ],
           "events": [
@@ -132,7 +155,7 @@
             },
             {
               "name": "max",
-              "description": "Value that fills the ring's range. Must be positive.",
+              "description": "Value that fills the ring's range. Must be positive. Without it, --o-max of the ring or system.",
               "type": {
                 "text": "number"
               },
@@ -197,6 +220,10 @@
             {
               "name": "--o-progress",
               "description": "Progress value; overrides the value attribute."
+            },
+            {
+              "name": "--o-max",
+              "description": "Value that fills the range when there is no max attribute. Default 100; cascades from the ring or system."
             }
           ],
           "events": [
@@ -245,6 +272,6 @@
   ],
   "package": {
     "name": "@zumer/orbit",
-    "version": "2.0.0"
+    "version": "2.1.0"
   }
 }

package/dist/orbit.css

@@ -1148,6 +1148,8 @@
   --o-gap: 1;
   --o-initial-orbit: 0;
   --o-angle: 0;
+  /* The value that fills a ring's range, for arcs and progress without a max attribute. */
+  --o-max: 100;
   width: 0;
   aspect-ratio: 1;
   position: relative;
@@ -1214,12 +1216,25 @@
   pointer-events: all;
 }
 
+/* The angle of the value of the <o-progress> in a ring, from the start of its
+   range. The progress writes it on its ring. */
+@property --o-value-angle {
+  syntax: "<angle>";
+  inherits: true;
+  initial-value: 0deg;
+}
 .satellite.at-center {
   --o-transform: rotate(0deg);
   --o-dir-x: 0;
   --o-dir-y: 0;
 }
 
+/* Sits on the value of the <o-progress> in the same ring, like the knob of a
+   dial. Progress always fills clockwise, so this ignores .ccw. */
+.satellite.at-value {
+  --o-angle-composite: calc(var(--o-value-angle) + 270deg);
+}
+
 .satellite.circle {
   border-radius: 50%;
 }
@@ -9638,6 +9653,33 @@ Can be used in parent elements or in each orbiter class
   margin-top: unset;
 }
 
+/*
+  Labels outside their satellite, away from the center (--o-dir-x/-y). Put
+  the class on a capsule or on an element inside one. 50cqw and 50cqh are half
+  the satellite; --o-outward-gap is the space between it and the label.
+*/
+.outward, .outward-y {
+  position: absolute;
+  width: max-content;
+}
+
+/* Along the direction. The translate scales the direction so its larger
+   component is 1: the label's nearest edge or corner touches the circle. */
+.outward {
+  --o-out: max(var(--o-dir-x), -1 * var(--o-dir-x), var(--o-dir-y), -1 * var(--o-dir-y), .001);
+  left: calc(50% + var(--o-dir-x) * (50cqw + var(--o-outward-gap, 4px)));
+  top: calc(50% + var(--o-dir-y) * (50cqh + var(--o-outward-gap, 4px)));
+  translate: calc(-50% + 50% * var(--o-dir-x) / var(--o-out)) calc(-50% + 50% * var(--o-dir-y) / var(--o-out));
+}
+
+/* Only up or down: above the satellites of the upper half, below the rest. */
+.outward-y {
+  --o-out: clamp(-1, (var(--o-dir-y) + .01) * 1000, 1);
+  left: 50%;
+  top: calc(50% + var(--o-out) * (50cqh + var(--o-outward-gap, 4px)));
+  translate: -50% calc((var(--o-out) - 1) * 50%);
+}
+
 /*  Satellite  gyro */
 .satellite.spin-lock {
   transform: var(--o-transform) rotate(calc(var(--o-angle-composite)));

package/dist/orbit.d.ts

@@ -18,8 +18,13 @@ type BooleanAttribute = boolean | '' | undefined;
 export interface OrbitArcAttributes {
   /** Share of the ring's range, relative to `max`. Without it, sibling arcs split the range equally. */
   value?: Numeric;
-  /** Value that fills the whole range. Default `100`. */
+  /** Value that fills the whole range. Default `--o-max` of the ring or system, else `100`. */
   max?: Numeric;
+  /**
+   * Where the arc begins, on the same scale as `value` (0 is the start of the range).
+   * A placed arc takes no slot and moves no other arc, so it can sit over a ring that already has arcs.
+   */
+  start?: Numeric;
   shape?: OrbitShape;
   /**
    * Where curved text sits on the arc. Default `middle`.
@@ -43,7 +48,7 @@ export interface OrbitArcAttributes {
 export interface OrbitProgressAttributes {
   /** Progress relative to `max`. `--o-progress` overrides it. */
   value?: Numeric;
-  /** Value that fills the whole range. Default `100`. */
+  /** Value that fills the whole range. Default `--o-max` of the ring or system, else `100`. */
   max?: Numeric;
   shape?: OrbitShape;
   /** `stroke` draws open lines colored by `--o-stroke` and `--o-back-stroke`. */
@@ -68,7 +73,10 @@ export declare class OrbitProgress extends HTMLElement {
   value: number | null;
   /** Mirrors the `max` attribute (default 100). Setting it redraws. */
   max: number;
-  /** Redraw now. The runtime calls this when the progress or its layout changes. */
+  /**
+   * Redraw now. The runtime calls this when the progress or its layout changes.
+   * It also writes `--o-value-angle` on its ring, where a `.satellite.at-value` sits.
+   */
   update(): void;
 }
 

package/dist/orbit.js

@@ -1,6 +1,6 @@
 /*
 * orbit
-* v.2.0.0
+* v.2.1.0
 * Author Juan Martin Muda - Zumerlab
 * License MIT
 */
@@ -100,7 +100,7 @@
     return Number.isFinite(resolved) ? resolved : fallback;
   }
   function group(element) {
-    if (element.localName === "o-arc") return "arc";
+    if (element.localName === "o-arc") return element.hasAttribute("start") ? null : "arc";
     for (const name of ["satellite", "vector", "side"]) if (element.classList.contains(name)) return name;
     return null;
   }
@@ -445,10 +445,22 @@
       }
       return value;
     }
-    /** The max attribute (default 100). It must be a positive number. */
-    readMax() {
+    /**
+     * The max attribute, else --o-max from the ring or system (default 100).
+     * It must be a positive number.
+     */
+    readMax(style) {
       const raw = this.getAttribute("max");
-      if (raw === null) return 100;
+      if (raw === null) {
+        const css = style == null ? void 0 : style.getPropertyValue("--o-max").trim();
+        if (!css) return 100;
+        const max2 = cssNumber(this, css, NaN);
+        if (!(max2 > 0)) {
+          warnOnce(this, "o-max:" + css, `--o-max: ${css} on <${this.localName}> must be a positive number, so nothing is drawn.`);
+          return 0;
+        }
+        return max2;
+      }
       const max = Number(raw);
       if (!(max > 0)) {
         warnOnce(this, "max:" + raw, `<${this.localName} max="${raw}"> must be a positive number, so nothing is drawn.`);
@@ -668,14 +680,15 @@
     }
     /**
      * Grow the SVG canvas past the ring's box so it covers the whole band, its
-     * stroke and touch area. Some engines (WebKit) neither paint reliably nor
-     * hit-test SVG content that overflows its box.
+     * stroke and touch area, and as far as a ripple reaches (attrs.reach).
+     * Some engines (WebKit) neither paint reliably nor hit-test SVG content that
+     * overflows its box.
      */
     fitCanvas(attrs, extra) {
       const svg = this.shadowRoot.querySelector("svg");
       const scale = attrs.orbitRadius / 50;
       if (!svg || !(scale > 0)) return;
-      const outer = (attrs.realRadius + attrs.arcHeightPercentage) * scale + attrs.strokeWidth + extra;
+      const outer = ((attrs.realRadius + attrs.arcHeightPercentage) * scale + attrs.strokeWidth) * (attrs.reach || 1) + extra;
       const pad = Math.max(0, Math.ceil(outer - attrs.orbitRadius));
       const units = pad / scale;
       svg.setAttribute("viewBox", `${-units} ${-units} ${100 + 2 * units} ${100 + 2 * units}`);
@@ -776,6 +789,16 @@
       this.shadowRoot.querySelector(".progress-bg").setAttribute("d", dBg);
       this.shadowRoot.querySelector(".progress-bar").setAttribute("d", dBar);
       this.updateHitArea(this.shadowRoot.querySelector(".hit"), attrs, 0, attrs.range);
+      const ring = this.parentElement;
+      if (this._valueRing && this._valueRing !== ring) this._valueRing.style.removeProperty("--o-value-angle");
+      this._valueRing = ring;
+      if (ring) setLayoutProperty(ring, "--o-value-angle", `${this.getProgressAngle(attrs, false)}deg`);
+    }
+    disconnectedCallback() {
+      var _a;
+      super.disconnectedCallback();
+      (_a = this._valueRing) == null ? void 0 : _a.style.removeProperty("--o-value-angle");
+      this._valueRing = null;
     }
     /**
      * variant="stroke": open arc along the orbit radius (no closed band),
@@ -793,7 +816,7 @@
       const range = Math.max(0, Math.min(360, this.readAngle(common.style, "--o-range", 360)));
       const rawValue = common.style.getPropertyValue("--o-progress").trim();
       const progress = rawValue ? this.readNumber(common.style, "--o-progress", 0) : this.readValue();
-      const maxValue = this.readMax();
+      const maxValue = this.readMax(common.style);
       return {
         ...common,
         range,
@@ -850,6 +873,12 @@
     :host([interactive]) svg * {
       pointer-events: visiblePainted;
     }
+    /* Text lets the pointer through to the band under it: WebKit fires no
+       click on SVG text inside a shadow root. */
+    :host([interactive]) svg text,
+    :host([interactive]) svg textPath {
+      pointer-events: none;
+    }
     /* The touch area catches the pointer even where the band is transparent. */
     #orbitHit {
       fill: none;
@@ -876,9 +905,32 @@
       stroke: none;
       pointer-events: none;
     }
+    /* .ripple: a copy of the band grows out from the center of the ring and
+       fades, over and over. The band itself stays. */
+    #orbitWave {
+      display: none;
+      fill: var(--o-ripple-color, var(--o-fill));
+      stroke: none;
+      pointer-events: none;
+      transform-origin: 50px 50px;
+    }
+    :host(.ripple) #orbitWave {
+      display: inline;
+      animation: orbit-ripple var(--o-ripple-duration, 1.6s) ease-out infinite;
+    }
+    @keyframes orbit-ripple {
+      from { transform: scale(1); opacity: .9; }
+      to { transform: scale(var(--o-ripple-scale, 1.14)); opacity: 0; }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :host(.ripple) #orbitWave {
+        display: none;
+      }
+    }
   </style>
   <svg viewBox="0 0 100 100">
     <path id="orbitHit" vector-effect="non-scaling-stroke"></path>
+    <path id="orbitWave" shape-rendering="geometricPrecision"></path>
     <path id="orbitShape" shape-rendering="geometricPrecision" vector-effect="non-scaling-stroke"></path>
     <path id="orbitPath" shape-rendering="geometricPrecision" vector-effect="non-scaling-stroke"></path>
     <text>
@@ -907,7 +959,9 @@
       const orbitPath = this.shadowRoot.querySelector("#orbitPath");
       const orbitShape = this.shadowRoot.querySelector("#orbitShape");
       const textPath = this.shadowRoot.querySelector("textPath");
-      orbitShape.setAttribute("d", this.calculateArcParameters(attrs).dShape);
+      const { dShape } = this.calculateArcParameters(attrs);
+      orbitShape.setAttribute("d", dShape);
+      this.shadowRoot.querySelector("#orbitWave").setAttribute("d", dShape);
       orbitPath.setAttribute("d", this.calculateTextArcParameters(attrs).dPath);
       this.updateHitArea(this.shadowRoot.querySelector("#orbitHit"), attrs, 0, attrs.arcAngle);
       const textAnchor = attrs.textAnchor;
@@ -968,26 +1022,45 @@
       const gap = Math.max(0, this.readNumber(style, "--o-gap", 1));
       const svgFontSize = `calc(${fontSize} * (100 / (${length}) * (12 / var(--o-orbit-number)))`;
       const auto = this.getAttribute("range") === "auto";
-      const stacked = auto || this.hasAttribute("value");
+      const valued = this.hasAttribute("value");
+      const placed = this.hasAttribute("start");
+      const stacked = auto || valued || placed;
+      const max = this.readMax(style);
       let arcAngle;
       if (auto) arcAngle = this.measureTextAngle(svgFontSize, common.realRadius, gap);
-      else if (this.hasAttribute("value")) arcAngle = super.getProgressAngle(range, this.readValue(), this.readMax());
+      else if (valued) arcAngle = super.getProgressAngle(range, this.readValue(), max);
       else arcAngle = Math.max(0, Math.min(360, this.readAngle(style, "--o-angle", 0)));
       this._autoAngle = auto ? arcAngle : 0;
       let stackOffset = 0;
-      if (stacked) {
+      if (placed) {
+        stackOffset = max > 0 ? this.readStart() / max * range : 0;
+        if (!auto && range < 360) {
+          const end = Math.min(range, stackOffset + arcAngle);
+          stackOffset = Math.max(0, stackOffset);
+          arcAngle = Math.max(0, end - stackOffset);
+        }
+      } else if (stacked) {
         for (let prev = this.previousElementSibling; prev; prev = prev.previousElementSibling) {
-          if (prev.localName !== "o-arc") continue;
+          if (prev.localName !== "o-arc" || prev.hasAttribute("start")) continue;
           const previousStyle = this.ownerDocument.defaultView.getComputedStyle(prev);
           if (prev.getAttribute("range") === "auto") stackOffset += prev._autoAngle || 0;
           else if (prev.hasAttribute("value")) {
-            const prevMax = prev.hasAttribute("max") ? Number(prev.getAttribute("max")) : 100;
+            const prevMax = this.readMax.call(prev, previousStyle);
             const prevRange = cssNumber(prev, previousStyle.getPropertyValue("--o-range"), range, "angle");
             stackOffset += super.getProgressAngle(prevRange, Number(prev.getAttribute("value")), prevMax);
           } else stackOffset += cssNumber(prev, previousStyle.getPropertyValue("--o-angle"), 0, "angle");
         }
       }
-      return { ...common, gap, arcAngle, stackOffset, flip, fitRange, length, fontSize, svgFontSize, textAnchor, auto, stacked };
+      const reach = this.classList.contains("ripple") ? Math.max(1, this.readNumber(style, "--o-ripple-scale", 1.14)) : 1;
+      return { ...common, gap, max, arcAngle, stackOffset, flip, fitRange, length, fontSize, svgFontSize, textAnchor, auto, placed, stacked, reach };
+    }
+    /** The start attribute: where a placed arc begins, on the ring's scale. */
+    readStart() {
+      const raw = this.getAttribute("start");
+      const start = Number(raw);
+      if (Number.isFinite(start)) return start;
+      warnOnce(this, "start:" + raw, `<o-arc start="${raw}"> is not a number, so the arc starts at 0.`);
+      return 0;
     }
     /** range="auto": the angle that fits this arc's text, with half an em of room at each end. */
     measureTextAngle(svgFontSize, radius, gap) {