@zumer/orbit 1.4.12 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +131 -123
  2. package/dist/orbit.css +520 -600
  3. package/dist/orbit.js +464 -157
  4. package/dist/orbit.min.css +1 -1
  5. package/dist/orbit.min.js +4 -4
  6. package/dist/orbit.mjs +946 -0
  7. package/package.json +14 -4
package/README.md CHANGED
@@ -1,186 +1,194 @@
1
- # Orbit CSS Composer
1
+ # Orbit
2
2
 
3
- **Orbit** is a CSS framework for building radial UIs — gauges, donuts, knobs, pie menus, dashboards — with **CSS only**. No layout JavaScript. Works with plain HTML and any framework (React, Vue, Svelte).
3
+ Orbit arranges HTML elements around a center. Use it to build radial menus, charts, gauges and other circular interfaces.
4
4
 
5
- <p align="center">
6
- <a href="https://zumerlab.github.io/orbit-docs" target="_blank"><strong>🚀 Live showcase &amp; docs</strong></a>
5
+ CSS controls geometry and appearance. A small JavaScript runtime updates the layout and draws arcs when elements, styles or values change. Orbit works with plain HTML, React, Vue and Svelte.
7
6
 
8
- </p>
7
+ [Examples and documentation](https://zumerlab.github.io/orbit-docs/) · [npm](https://www.npmjs.com/package/@zumer/orbit)
9
8
 
10
- <p align="center">
11
- <a href="https://www.npmjs.com/package/@zumer/orbit"><img src="https://img.shields.io/npm/v/@zumer/orbit" alt="npm"></a>
12
- <a href="https://github.com/zumerlab/orbit/stargazers"><img src="https://img.shields.io/github/stars/zumerlab/orbit" alt="Stars"></a>
13
- </p>
9
+ ## Install
14
10
 
15
- ---
11
+ ```sh
12
+ npm install @zumer/orbit
13
+ ```
16
14
 
17
- ## Why Orbit?
15
+ Import the stylesheet and runtime in your app's client entrypoint:
18
16
 
19
- Radial UIs usually need JavaScript to compute angles, radii, and positions. **Orbit** handles all of that with CSS classes and a couple of Web Components. Drop in two files and start building.
17
+ ```js
18
+ import '@zumer/orbit/style'
19
+ import '@zumer/orbit'
20
+ ```
20
21
 
21
- > **Want ready-made components?** [**orbit-kit**](https://zumerlab.com/orbit-kit) wraps the common Orbit patterns into one-line custom elements — gauges, charts, activity rings, knobs, pie menus, cockpit instruments, analog clocks, compasses and radars.
22
+ For a plain HTML page, load the files from a CDN as shown below.
22
23
 
23
- ## Installation
24
+ ## A progress ring
24
25
 
25
- **CDN (fastest):**
26
+ Save this as `index.html` and open it in a browser. It loads Orbit from the CDN and draws a ring at 72%.
26
27
 
27
28
  ```html
28
- <link rel="stylesheet" href="https://unpkg.com/@zumer/orbit@latest/dist/orbit.css">
29
- <script src="https://unpkg.com/@zumer/orbit@latest/dist/orbit.js"></script>
29
+ <!doctype html>
30
+ <html lang="en">
31
+ <head>
32
+ <meta charset="utf-8">
33
+ <meta name="viewport" content="width=device-width, initial-scale=1">
34
+ <title>Orbit progress ring</title>
35
+ <link rel="stylesheet" href="https://unpkg.com/@zumer/orbit@1.5.0/dist/orbit.min.css">
36
+ <script defer src="https://unpkg.com/@zumer/orbit@1.5.0/dist/orbit.min.js"></script>
37
+ <style>
38
+ body { margin: 0; min-height: 100vh; display: grid; place-items: center; }
39
+ .gauge.bigbang { width: 240px; height: 240px; }
40
+ .gauge > .gravity-spot { --o-force: 400px; }
41
+ .gauge o-progress { --o-fill: #3da9fc; --o-back-fill: #1d3749; --o-stroke: none; }
42
+ </style>
43
+ </head>
44
+ <body>
45
+ <div class="gauge bigbang">
46
+ <div class="gravity-spot">
47
+ <div class="orbit-6">
48
+ <o-progress value="72" shape="rounded" role="progressbar"
49
+ aria-label="Upload progress" aria-valuenow="72"
50
+ aria-valuemin="0" aria-valuemax="100"></o-progress>
51
+ </div>
52
+ </div>
53
+ </div>
54
+ </body>
55
+ </html>
30
56
  ```
31
57
 
32
- **npm:**
33
-
34
- ```bash
35
- npm install @zumer/orbit
36
- ```
58
+ Change the `value` attribute to update the ring. Keep any labels or ARIA values you add in sync with it:
37
59
 
38
60
  ```js
39
- import '@zumer/orbit/style'
40
- import '@zumer/orbit'
61
+ const progress = document.querySelector('o-progress')
62
+ progress.setAttribute('value', '40')
63
+ progress.setAttribute('aria-valuenow', '40')
41
64
  ```
42
65
 
43
- ---
66
+ The runtime redraws the ring automatically. A value of `0` leaves only the background; `100` fills the orbit's range.
67
+
68
+ ## How layouts fit together
69
+
70
+ A `.bigbang` container holds a `.gravity-spot`, which defines the center. Rings inside it position the content. In the example above, `.orbit-6` sets the ring's radius and `<o-progress>` draws on it.
71
+
72
+ | Element | Purpose |
73
+ | --- | --- |
74
+ | `.bigbang` | Container that centers the layout. |
75
+ | `.gravity-spot` | Layout origin; holds rings and defines their scale with `--o-force`. |
76
+ | `.orbit` / `.orbit-N` | Ring with an automatic index or an explicit level, such as `.orbit-6`. |
77
+ | `.satellite` | Positions an item on a ring. |
78
+ | `.capsule` | Wraps content inside a satellite. |
79
+ | `.vector` | Places a tick or marker on a ring. |
80
+ | `.side` | Places content along the straight line between adjacent ring positions. |
81
+ | `<o-arc>` | Draws a segment. Sibling arcs stack in HTML order. |
82
+ | `<o-progress>` | Draws a progress value over a background arc. |
83
+
84
+ Put rings directly inside `.gravity-spot`, not inside other rings. Use `.capsule` for elements inside a satellite, or a nested `.gravity-spot` for another radial layout. `.orbit-0` places content at the center.
44
85
 
45
- ## Quick start
86
+ Set `--o-range` to control the angular span and `--o-from` to rotate it. Classes such as `range-270`, `from-180` and `fit-range` provide common settings. The [element reference](https://zumerlab.github.io/orbit-docs/elements/orbit/) covers sizing, spacing and nesting.
46
87
 
47
- Minimal gauge in 10 lines:
88
+ Arcs and progress elements use `value` relative to `max`, which defaults to `100`, and support circular rings. Add `interactive` when you need their SVG shapes to receive pointer events; they are decorative by default. Supply the keyboard behavior and accessible labels for any controls you build.
89
+
90
+ Progress rings draw filled bands by default. For a stroked line, use `variant="stroke"` and set `--o-stroke` and `--o-back-stroke` instead of the fill colors.
91
+
92
+ ### Depth layers
93
+
94
+ Add `depth` to a `.gravity-spot` to stack its rings in 3D. Each direct child ring (or a nested `.bigbang`) is a layer: `data-depth="1"` moves it one step back, and `.layer-front` marks the active layer at depth 0. Layers keep their apparent size, because the scale compensates for the perspective, and they animate when their depth changes.
48
95
 
49
96
  ```html
50
- <div class="bigbang">
51
- <div class="gravity-spot">
52
- <div class="orbit-4">
53
- <o-progress value="72"></o-progress>
54
- </div>
55
- </div>
97
+ <div class="gravity-spot depth" style="--o-depth-grow: .42">
98
+ <div class="orbit-4 layer-front"><o-progress value="82"></o-progress></div>
99
+ <div class="orbit-4" data-depth="1"><o-progress value="40"></o-progress></div>
100
+ <div class="orbit-4" data-depth="2"><o-progress value="65"></o-progress></div>
56
101
  </div>
57
102
  ```
58
103
 
59
- **Structure:** `bigbang` (container) → `gravity-spot` (center) → `orbit-N` (ring level) → `o-progress` or `o-arc` (the visual element).
60
-
61
- ---
104
+ | Property | Default | Purpose |
105
+ | --- | --- | --- |
106
+ | `--o-z` | `depth × step` | Position on the z axis in unitless pixels; negative values are farther away. Set it on a ring to override `data-depth`. |
107
+ | `--o-depth-step` | `-110` | Distance between depth steps. |
108
+ | `--o-perspective` | `900` | Perspective in unitless pixels. |
109
+ | `--o-depth-grow` | `0` | Extra size per step back; `.42` gives 1×, 1.42×, 1.84×. |
110
+ | `--o-depth-compensate` | `1` | Set to `0` to let farther layers look smaller. |
111
+ | `--o-back-opacity` | `1` | Opacity of layers behind the front one. |
112
+ | `--o-depth-duration` / `--o-depth-easing` | `.8s` / `cubic-bezier(.2,.8,.2,1)` | Depth transition. Disabled with `prefers-reduced-motion`. |
62
113
 
63
- ## Core elements
114
+ `data-depth` accepts 0 to 8. Rings outside `.depth` are not transformed.
64
115
 
65
- | Element | Role |
66
- |---------|------|
67
- | `.bigbang` | Root container, sets viewport |
68
- | `.gravity-spot` | Center of the radial layout; holds rings |
69
- | `.orbit-1` … `.orbit-7` | Rings at different radii (1 = innermost) |
70
- | `.satellite` | Item placed on a ring (dot, label, icon) |
71
- | `<o-arc>` | Arc segment (donut slice, gauge needle, menu sector); `value` 0–100, `shape` e.g. `arrow`, `circle-a` |
72
- | `<o-progress>` | Simple progress ring |
73
- | `.vector` | Tick/marker on a ring |
74
- | `.side` | Stretch content along arc |
75
- | `.capsule` | Wrapper for content inside satellite; required when satellite holds more than plain text |
116
+ ## In an app
76
117
 
77
- **Structure rules (avoid visual warnings):**
78
- - `.bigbang` → direct children: `.gravity-spot` only
79
- - `.gravity-spot` → direct children: `.orbit`, `.orbit-N`, or `.gravity-spot` only
80
- - `.satellite` → direct children: `.capsule` or `.gravity-spot` (for nesting) only
81
- - `.orbit` / `.orbit-N` → do not nest other orbits; orbits live inside gravity-spot
82
- - `o-arc` and `o-progress` → only work in circular orbits; they are hidden in elliptical shapes
118
+ Orbit observes added, removed and reordered elements, style and attribute changes, and container resizes. Updates are grouped into the next animation frame.
83
119
 
84
- **Useful classes:** `range-180`, `range-270`, `range-360` (arc span); `from-180` (start angle); `fit-range` (distribute items); `shrink-50`, `gap-4` (spacing); `at-center` (place satellite in middle).
120
+ Importing the package during server rendering is safe. Include it in the browser entrypoint too, so it can register the custom elements and observe the rendered layout. The module exports `Orbit`, `OrbitArc`, `OrbitProgress` and `registerOrbit`; registration happens on import, and repeated calls to `registerOrbit()` are safe.
85
121
 
86
- ---
122
+ Use `Orbit.refresh()` when you need an immediate update, or after changes Orbit cannot observe, such as editing stylesheet rules through CSSOM or changing an external control used by a CSS selector:
87
123
 
88
- ## Themes
124
+ ```js
125
+ import { Orbit } from '@zumer/orbit'
89
126
 
90
- Orbit includes built-in themes. Add the theme class to `.bigbang`:
127
+ const panel = document.querySelector('#instrument-panel')
128
+ Orbit.refresh(panel)
129
+ ```
91
130
 
92
- | Theme | Class | Description |
93
- |-------|-------|-------------|
94
- | **Default** | *(none)* | Transparent borders, gray fills, satellites use `currentColor` |
95
- | **Cyan** | `theme-cyan` | Cyan satellite borders, cyan vectors/sides, light cyan fills for `o-arc` and `o-progress` |
96
- | **Developer** | `dev-orbit` | Dashed red borders on orbits and satellites to visualize structure while debugging |
131
+ `refresh()` accepts an element, document or shadow root. With no argument, it refreshes the document. The CDN script exposes the same API as `window.Orbit`.
97
132
 
98
- ```html
99
- <!-- Default (no class) -->
100
- <div class="bigbang">...</div>
133
+ To scale a layout with its container's width, call `Orbit.resize()` after that container mounts:
101
134
 
102
- <!-- Cyan theme -->
103
- <div class="bigbang theme-cyan">...</div>
135
+ ```js
136
+ const stopResizing = Orbit.resize('#instrument-panel')
104
137
 
105
- <!-- Developer mode for layout debugging -->
106
- <div class="bigbang dev-orbit">...</div>
138
+ // Call stopResizing() when the component unmounts.
107
139
  ```
108
140
 
109
- You can combine themes, e.g. `class="bigbang theme-cyan dev-orbit"`.
141
+ `resize()` accepts a selector or an element. It uses a 500px base scale and returns a function that disconnects its observer.
110
142
 
111
- ---
143
+ For shadow DOM, include the stylesheet inside each shadow root. An `<o-arc>` or `<o-progress>` registers its layout there automatically. If the shadow tree contains only CSS elements, register it with `Orbit.refresh(shadowRoot)`. Open and closed roots are supported.
112
144
 
113
- ## Visual aids & development
145
+ Use the documented CSS properties for overrides. The runtime manages `data-orbit-ring`, `--o-layout-*` and `--o-arc-start` internally.
114
146
 
115
- Orbit provides **CSS visual warnings** to catch invalid structure. When rules are broken (e.g. wrong children in `gravity-spot` or `satellite`), Orbit shows a red dotted border, grays out content, and displays a ⚠️ icon.
147
+ ## Browser support and debugging
116
148
 
117
- Add **`class="dev-orbit"`** to your root container to enable **developer mode**: dashed red borders on `gravity-spot`, `orbit`, and `satellite` to visualize the layout structure. Useful for debugging.
149
+ Orbit needs CSS trigonometric functions (`sin` and `cos`). Without JavaScript, a CSS fallback can position simple elements on up to 24 ring levels, with up to 60 children per type; it also requires `:has()` and `:nth-child(... of ...)`. The JavaScript runtime supports larger layouts. `<o-arc>` and `<o-progress>` always need JavaScript.
150
+
151
+ Add `dev-orbit` to a container to show ring boundaries and invalid nesting. Add `theme-cyan` for the built-in cyan colors; both classes can be combined:
118
152
 
119
153
  ```html
120
- <div class="bigbang dev-orbit">
121
- <div class="gravity-spot">
122
- ...
123
- </div>
124
- </div>
154
+ <div class="bigbang theme-cyan dev-orbit">...</div>
125
155
  ```
126
156
 
127
- Orbit also checks browser support for `:has()` and trigonometric CSS functions (`cos`, `sin`); unsupported browsers show an upgrade message. See [CSS visual aids](https://zumerlab.github.io/orbit-docs/tools/support) in the full docs.
128
-
129
- ---
157
+ The [visual aids guide](https://zumerlab.github.io/orbit-docs/tools/support/) explains the structural checks.
130
158
 
131
- ## Examples
159
+ ## Examples and components
132
160
 
133
- Browse examples on the [Orbit docs site](https://zumerlab.github.io/orbit-docs):
161
+ Browse [gauges](https://zumerlab.github.io/orbit-docs/examples/gauges/), [charts](https://zumerlab.github.io/orbit-docs/examples/charts/), [radial menus](https://zumerlab.github.io/orbit-docs/examples/piemenu/), [knobs](https://zumerlab.github.io/orbit-docs/examples/knobs/) and [watch faces](https://zumerlab.github.io/orbit-docs/examples/watches/).
134
162
 
135
- | Example | Link |
136
- |---------|------|
137
- | Circular timer | [circular_time](https://zumerlab.github.io/orbit-docs/examples/circular_time/) |
138
- | Progress bars | [progress](https://zumerlab.github.io/orbit-docs/examples/progress/) |
139
- | Charts (donut, pie, sunburst) | [charts](https://zumerlab.github.io/orbit-docs/examples/charts/) |
140
- | Gauges (180°, 240°, fuel) | [gauges](https://zumerlab.github.io/orbit-docs/examples/gauges/) |
141
- | Knobs | [knobs](https://zumerlab.github.io/orbit-docs/examples/knobs/) |
142
- | Pie menus | [piemenu](https://zumerlab.github.io/orbit-docs/examples/piemenu/) |
143
- | Watch faces | [watches](https://zumerlab.github.io/orbit-docs/examples/watches/) |
144
- | Chemical structures | [chemical_structures](https://zumerlab.github.io/orbit-docs/examples/chemical_structures/) |
145
- | Calendars & time planners | [calendar](https://zumerlab.github.io/orbit-docs/examples/calendar/) |
146
- | Mandalas | [mandalas](https://zumerlab.github.io/orbit-docs/examples/mandalas/) |
147
- | Dashboard | [dashboard](https://zumerlab.github.io/orbit-docs/examples/dashboard/) |
148
- | Abstract orbital map | [abstract_map](https://zumerlab.github.io/orbit-docs/examples/abstract_map/) |
163
+ [Orbit Kit](https://zumerlab.com/orbit-kit) provides ready-made gauges, clocks, knobs and menus built on Orbit. Use the base library when you want to compose the layout yourself.
149
164
 
150
- ---
165
+ ## Work on Orbit
151
166
 
152
- ## Use cases
167
+ From a local checkout:
153
168
 
154
- - **Dashboards:** gauges, status rings, KPIs
155
- - **Automotive / HUD:** speedometers, tachometers, battery, temp
156
- - **IoT / Smart home:** thermostats, energy rings, scenes
157
- - **Ops / monitoring:** status rings, uptime gauges
158
- - **Fitness / health:** activity rings (Move, Exercise, Stand)
159
- - **Controls:** knobs, radial menus, compass
169
+ ```sh
170
+ npm ci
171
+ npm run demo
172
+ ```
160
173
 
161
- ---
174
+ Open <http://127.0.0.1:5174>. The demo command compiles the source and serves the playground with that local build. Use `PORT=5175 npm run demo` to choose another port.
162
175
 
163
- ## Using Orbit with AI / LLMs
176
+ To run the tests:
164
177
 
165
- Orbit's radial model is unlike the box-flow layouts most models were trained on,
166
- so an assistant generating Orbit markup from scratch will struggle. Give it the
167
- reference first — these files are written for that purpose:
178
+ ```sh
179
+ npx playwright install chromium firefox webkit
180
+ BROWSERS=chromium,firefox,webkit npm test
181
+ ```
168
182
 
169
- - **[llms.txt](https://zumerlab.github.io/orbit-docs/llms.txt)** — concise overview, structure rules, quick recipes.
170
- - **[llms-full.txt](https://zumerlab.github.io/orbit-docs/llms-full.txt)** — complete reference: every class, custom property, web component, and copy-paste pattern.
183
+ The tests cover package contents, server imports, browser layouts and shadow DOM. `npm test` uses Chromium by default. Run `npm run test:package`, `npm run test:browser` or `npm run test:shadow` for an individual suite.
171
184
 
172
- Paste the relevant one into your prompt (or your tool's context/rules) before
173
- asking the model to build a radial UI.
185
+ `npm run compile` writes the CSS and JavaScript files to `dist/`. `npm run build` also creates the npm tarball.
174
186
 
175
- ## Resources
187
+ ## Contributing and reference
176
188
 
177
- - [orbit-kit](https://zumerlab.com/orbit-kit) — ready-made radial components built on Orbit
178
- - [Full documentation](https://zumerlab.github.io/orbit-docs) — elements, tools, advanced examples
179
- - [Contributing](CONTRIBUTING.md)
180
- - [GitHub Discussions](https://github.com/zumerlab/orbit/discussions)
181
- - [Telegram](https://t.me/ZumlyCommunity)
189
+ Report bugs in [Issues](https://github.com/zumerlab/orbit/issues), or share examples and ask questions in [Discussions](https://github.com/zumerlab/orbit/discussions). See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution details. There is also a [Telegram group](https://t.me/ZumlyCommunity).
182
190
 
183
- ---
191
+ For coding assistants, [llms.txt](https://zumerlab.github.io/orbit-docs/llms.txt) has a short reference and [llms-full.txt](https://zumerlab.github.io/orbit-docs/llms-full.txt) has the full class and property reference. Include the relevant sections when asking an assistant to generate Orbit markup.
184
192
 
185
193
  ## License
186
194