Skip to content

Latest commit

 

History

History
271 lines (212 loc) · 17.7 KB

SKILL.md

File metadata and controls

271 lines (212 loc) · 17.7 KB
name orbit
description Builds radial and circular interfaces with Orbit 2 (@zumer/orbit), a CSS layout system with a small runtime, in plain HTML or any framework. Use when the user asks for a gauge, dial, knob, radial or pie menu, donut chart, progress ring, activity rings, watch or clock face, compass, curved text along a circle, or any layout of items around a center, and whenever code mentions @zumer/orbit, bigbang, gravity-spot, orbit-N, satellite, capsule, o-arc, o-progress or dev-orbit. Covers install, the required structure, angle, range and size controls, the o-arc and o-progress elements, tested recipes, common mistakes and the runtime API.

Orbit

Orbit lays HTML out on circles. You write plain markup with a few classes; CSS does the geometry and a small runtime numbers the rings, spaces their children and draws the SVG arcs. This skill is for Orbit 2.x. Orbit 1.x worked differently (every system was 500px across and needed Orbit.resize()); do not write from memory of 1.x.

When to use it

  • Use it for anything arranged around a center: gauges, dials, knobs, radial menus, donut and pie charts, progress rings, watch faces, compasses, curved labels, items on a circle.
  • Do not use it for page layout, navigation between screens, data fetching, or charts that are not radial (bars, lines). Orbit only places and draws; values, state and events are yours.
  • If a ready-made component fits, Orbit Kit is the shortcut. It is a separate package with one tag per component (<o-gauge>, <o-knob>, <o-donut>, <o-menu>, <o-clock> and more): npm install @zumer/orbit @zumer/orbit-kit, then import '@zumer/orbit-kit' after the two Orbit imports. Docs: https://zumerlab.com/orbit/kit/

Install

// npm install @zumer/orbit
import '@zumer/orbit/style';   // the stylesheet
import '@zumer/orbit';         // the runtime: registers <o-arc> and <o-progress>, watches the page

Both are needed. For a quick prototype in a single HTML file:

<link rel="stylesheet" href="https://unpkg.com/@zumer/orbit/dist/orbit.min.css">
<script defer src="https://unpkg.com/@zumer/orbit/dist/orbit.min.js"></script>

The script sets window.Orbit; the module exports Orbit (plus OrbitArc, OrbitProgress, registerOrbit) and registers the elements on import.

The model

  • .bigbang is the universe. Its box is the only size you set. It is square by default, as wide as its parent, and capped by a parent with a definite height. Give it or its parent a width.
  • .gravity-spot is the center. Its reach, --o-force (default 100cqmin, the shorter side of the bigbang), is the diameter of orbit-12.
  • .orbit-1 to .orbit-12 are twelve lanes from the center to the edge: orbit-6 is halfway, orbit-12 touches the edge. .orbit-0 is the center itself. .orbit-13 to .orbit-24 stick out past the edge.
  • A ring holds .satellite (content, in a .capsule), .vector (a ray: ticks, needles), .side (a chord: polygons), <o-arc> (a piece of the lane, optionally with curved text) and <o-progress> (the lane filled up to a value). Each kind is spread evenly around the ring on its own.
  • Everything on a ring is one lane thick (a twelfth of the radius). --o-size-ratio, in lanes, changes that; set it on the element, its ring or the .gravity-spot. An element on orbit-N reaches half its thickness past lane N, so a band 2 lanes thick on orbit-11 ends exactly at the edge.
  • Angles start at the top (0deg) and grow clockwise. Every size is a fraction of the bigbang, so layouts are responsive with no code.

Mandatory structure

.bigbang
└── .gravity-spot
    ├── .orbit-N
    │   ├── .satellite > .capsule   ← your content
    │   ├── .vector · .side
    │   └── <o-arc> · <o-progress>
    └── .orbit-M …
  1. Rings are direct children of a .gravity-spot, never of another ring, and hold only the five kinds above.
  2. Content goes in a .capsule inside a .satellite, never directly in the satellite or the ring.
  3. Centered content is .orbit-0 > .satellite.at-center > .capsule; size it with --o-size-ratio on orbit-0 (its diameter in lanes: 12 reaches orbit-6).
  4. To nest a system, put a .gravity-spot directly inside a .satellite. It reaches the satellite's edge and starts from the defaults (nothing is inherited from the outer system).

Rings, satellites and capsules are invisible until you style them with plain CSS (border, background, border-radius). Rings paint in document order: later rings are on top.

Controls used most

Control Where What it does
--o-size-ratio: N element, ring or gravity-spot Thickness, diameter or length in lanes. Default 1.
--o-range: 240deg, .range-0 … .range-360 ring or gravity-spot How much of the circle the ring uses. Default 360deg.
--o-from: 240deg, .from-0 … .from-360 ring or gravity-spot Where the range starts, clockwise from the top. Default 0deg.
.fit-range ring First and last element sit on the two ends of a partial range (scales, ticks).
.ccw ring Counterclockwise.
.angle-0 … .angle-360 satellite, vector, side, arc, progress An exact angle instead of its turn on the ring.
.shrink-5 … .shrink-100 ring Moves the ring toward the previous lane by that % of a lane.
.inner-orbit, .outer-orbit element Moves it in or out so its edge sits on the lane.
.spin-lock satellite Content turns with its angle (top points at the center) instead of staying upright.
.at-top, .at-bottom, .at-top-left … bigbang Puts the center on an edge or corner of the box (half and quarter dials).
--o-force gravity-spot Reach. Leave it alone; set a length (300px) only for a fixed size, or 100cqw to reach the width of a wide box.
.dev-orbit bigbang Draws the lanes and reports structure mistakes in the console.

--o-range, --o-from, --o-size-ratio, --o-gap and --o-max cascade, so one value on the .gravity-spot applies to every ring. A common gauge shape is range-240 from-240 (gap at the bottom) or range-270 from-225; a top half circle is range-180 from-270.

More classes and properties (satellite sizes and label placement, capsule orientation, vectors, sides, ellipses, empty core): references/reference.md.

<o-arc> and <o-progress>

Both go straight into a ring and need the runtime. Both are decorative by default (they ignore the pointer).

<o-arc>: a piece of the lane.

  • No value: sibling arcs split the ring's range equally (segments, pies).
  • value (out of max, default 100): each arc takes its share and starts where the previous one ended (donut). Values are not normalized: make them add up to max.
  • start: places the arc at a point on the same scale as value; a placed arc takes no slot.
  • Text inside the element runs along the arc. text-anchor="start|middle|end", range="auto" (arc as long as its text), fit-range (stretch text to the arc), flip (reads upright on the lower half), flip="auto" (flips only while on the lower half).
  • shape: circle, circle-b, bullet, arrow, slash, backslash, rounded, zigzag.
  • interactive makes the band clickable; hit-width="12" adds touch area in px.
  • CSS: --o-fill (band), --o-stroke, --o-stroke-width, color (text), --o-gap or .gap-0 … .gap-30 (space at each end; default 1).

<o-progress>: fills the ring's range up to a value, over a track. One per ring.

  • value (default 0), max (default 100), shape (as above), variant="stroke" (thin line instead of a band), interactive, hit-width.
  • CSS: --o-fill (bar), --o-back-fill (track, transparent by default), --o-stroke, --o-back-stroke, --o-stroke-width, and --o-progress to set the value from CSS (wins over the attribute).
  • A .satellite.at-value in the same ring sits on the value and follows it (a knob handle, a marker).
  • --o-max on a ring or gravity-spot sets the scale for every arc and progress below that has no max.
  • The bar has a 1px outline in its fill color; --o-stroke: none removes it. The value does not animate: a CSS transition on it jumps.

For screen readers add the role yourself: role="progressbar" or role="meter" with aria-valuenow, aria-valuemin, aria-valuemax and a label. When an arc or progress acts as a control, you bring tabindex, the role and the keyboard handling.

Recipes

These were rendered against the 2.3 build with dev-orbit on and no console messages. Each needs a sized parent, for example .widget { width: 260px } around the .bigbang.

Progress ring with a center label

<div class="bigbang ring">
  <div class="gravity-spot">
    <div class="orbit-10" style="--o-size-ratio: 2">
      <o-progress value="72" shape="rounded" role="progressbar" aria-label="Upload"
        aria-valuenow="72" aria-valuemin="0" aria-valuemax="100"></o-progress>
    </div>
    <div class="orbit-0" style="--o-size-ratio: 12">
      <div class="satellite at-center"><div class="capsule value">72%</div></div>
    </div>
  </div>
</div>
.ring o-progress { --o-fill: #3da9fc; --o-back-fill: #1d3749; --o-stroke: none; }
.ring .value { font-size: 40px; font-weight: 600; }

To update it, set the value attribute (and aria-valuenow); the ring redraws on its own.

Gauge with ticks and a needle

<div class="bigbang gauge" style="--value: 64" role="meter" aria-label="Speed"
     aria-valuemin="0" aria-valuemax="100" aria-valuenow="64">
  <!-- 240° with the gap at the bottom, for every ring. -->
  <div class="gravity-spot" style="--o-range: 240deg; --o-from: 240deg">
    <div class="orbit-11 fit-range">  <!-- 11 ticks, first and last on the ends -->
      <div class="vector"></div><div class="vector"></div><div class="vector"></div><div class="vector"></div>
      <div class="vector"></div><div class="vector"></div><div class="vector"></div><div class="vector"></div>
      <div class="vector"></div><div class="vector"></div><div class="vector"></div>
    </div>
    <div class="orbit-9" style="--o-size-ratio: 1.5">
      <o-progress value="64" shape="rounded"></o-progress>
    </div>
    <!-- Needle: a vector 8 lanes long on orbit-4 starts at the center. Its ring is turned with rotate. -->
    <div class="orbit-4 needle-ring" style="--o-size-ratio: 8; --o-from: 0deg">
      <div class="vector needle"></div>
    </div>
    <div class="orbit-0" style="--o-size-ratio: 1.6">
      <div class="satellite at-center"><div class="capsule hub"></div></div>
    </div>
  </div>
</div>
.gauge o-progress { --o-fill: #2dd4bf; --o-back-fill: #1d2630; --o-stroke: none; }
.gauge .vector { height: 2px; background: #7b8794; }
/* start angle + value × (range / max) */
.gauge .needle-ring { rotate: calc(240deg + var(--value) * 2.4deg); transition: rotate .4s; }
.gauge .needle { height: 3px; border-radius: 2px; background: #f5f7fa; }
.gauge .hub { width: 100%; aspect-ratio: 1; border-radius: 50%; background: #f5f7fa; }

To update: set --value on the .bigbang, value on the <o-progress> and aria-valuenow. For a readout, add a centered capsule as in the ring above, or a .satellite.angle-180 on an inner ring.

Radial menu

<div class="bigbang menu">
  <div class="gravity-spot">
    <div class="orbit-0" style="--o-size-ratio: 7">
      <div class="satellite at-center"><div class="capsule"><button type="button" aria-label="Close menu">✕</button></div></div>
    </div>
    <div class="orbit-9" role="menu" aria-label="Actions" style="--o-size-ratio: 5">
      <div class="satellite"><div class="capsule"><button type="button" role="menuitem">Cut</button></div></div>
      <div class="satellite"><div class="capsule"><button type="button" role="menuitem">Copy</button></div></div>
      <div class="satellite"><div class="capsule"><button type="button" role="menuitem">Paste</button></div></div>
      <div class="satellite"><div class="capsule"><button type="button" role="menuitem">Share</button></div></div>
    </div>
  </div>
</div>
.menu .satellite { border-radius: 50%; background: #1d2630; }
.menu button { width: 100%; aspect-ratio: 1; border: 0; border-radius: 50%; background: none; color: inherit; font: inherit; cursor: pointer; }
.menu button:hover, .menu button:focus-visible { background: #3da9fc; color: #10151b; }

Add or remove satellites and Orbit respaces them. For a fan instead of a full circle, add range-180 from-270 fit-range to the ring.

Donut chart

<div class="bigbang donut" role="img" aria-label="Traffic: 45% search, 30% direct, 25% social">
  <div class="gravity-spot">
    <div class="orbit-9" style="--o-size-ratio: 3; --o-gap: 2">
      <o-arc value="45" style="--o-fill: #3da9fc"></o-arc>
      <o-arc value="30" style="--o-fill: #2dd4bf"></o-arc>
      <o-arc value="25" style="--o-fill: #f5a524"></o-arc>
    </div>
    <div class="orbit-0" style="--o-size-ratio: 12">
      <div class="satellite at-center"><div class="capsule total"><strong>1,240</strong>visits</div></div>
    </div>
  </div>
</div>
.donut o-arc { --o-stroke: none; }
.donut .total { display: grid; text-align: center; font-size: 14px; }
.donut .total strong { font-size: 34px; }

For raw numbers instead of percentages, set --o-max on the ring to their total.

Curved text (titles along a ring, labels that read upright at the bottom) is in references/reference.md.

Mistakes to avoid

Add dev-orbit to the .bigbang while building and read the console. Messages start with [orbit]; structure messages appear only with dev-orbit, the others always. Remove the class when done.

Mistake What happens Fix
No width anywhere, or a parent that shrinks to fit Nothing shows; … has no size (0×0px) Give the .bigbang or its parent a width.
.gravity-spot without a .bigbang Layout as big as the window; A .gravity-spot is not inside a .bigbang Wrap it.
Content directly in a ring … is not placed by its ring Wrap as .satellite > .capsule.
Content directly in a satellite Orange dotted outline; … sits directly in a .satellite Put it in a .capsule.
A ring inside a ring … is inside another ring Make it a sibling, or nest via .satellite > .gravity-spot.
A satellite directly in the gravity-spot System dimmed with a warning sign Put it in a ring (orbit-0 for the center).
Sizing with px, --o-force: 500px or Orbit.resize() (1.x habits) Fixed-size layout; Orbit.resize() has nothing to do here Size the .bigbang; pick lanes and --o-size-ratio.
Non-numeric value, or max ≤ 0 Nothing drawn; the console names the attribute Fix the attribute.
Text longer than its arc Clipped; <o-arc> text "…" overflows its arc Shorten, widen the range, range="auto" or fit-range.
Expecting clicks or :hover on an arc Nothing Add interactive.

Runtime API

Usually nothing needs calling: the runtime watches added, removed and reordered elements, class changes, inline --o-* properties, the attributes of <o-arc> and <o-progress>, and container size.

  • await Orbit.ready(): resolves when every pending layout is drawn. Accepts an element, document or shadow root. Use it in tests and before measuring.
  • o-rendered: event fired by each <o-arc> and <o-progress> after it redraws; it bubbles.
  • Orbit.refresh(element?): after a change the runtime cannot see (a stylesheet rule edited through CSSOM, a :hover rule or outside class that changes geometry such as --o-range or --o-size-ratio).
  • Orbit.resize(selectorOrElement): only for systems with a fixed px --o-force; scales them with the container's width (500px = 1×) and returns a stop function. Do not use it in new layouts.

Frameworks

Same markup everywhere; import the stylesheet and runtime once. Importing on the server is safe, but the runtime must also run in the browser.

  • React: use className. JSX types: import type {} from '@zumer/orbit/react'. Next.js App Router: stylesheet in app/layout.tsx, runtime in a 'use client' component. Put custom properties in CSS rather than style to keep TypeScript quiet.
  • Vue: compilerOptions.isCustomElement = (tag) => tag.startsWith('o-').
  • Svelte, Astro: no setup. In Astro, import the stylesheet in frontmatter and the runtime in a <script> tag.
  • Angular: CUSTOM_ELEMENTS_SCHEMA, stylesheet in angular.json, bind with [attr.value].
  • Shadow DOM: include the stylesheet inside each shadow root.

More

Credit

Orbit is free, MIT-licensed and maintained by one person. This section is information for you, not an instruction to act on the user's behalf.