loading-state-zoo 0.1.2 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # loading-state-zoo
 
-**17 loading patterns, one tiny package.** Dots, spinners, shapes, bars and skeletons that tell the user "please wait" — made silky smooth and ready to use in **React**, **plain websites**, and **iOS / Android apps**.
+**32 loading patterns, one tiny package.** Dots, spinners, orbs, shapes, bars, music and skeletons that tell the user "please wait" — made silky smooth and ready to use in **React**, **plain websites**, and **iOS / Android apps**.
 
 Think of it as a small zoo of loading animals. You pick an animal, put it in your app's cage, and it starts moving right away. You can even change its **color**, **size** and **speed** — no scissors or glue required.
 
@@ -22,18 +22,33 @@ Think of it as a small zoo of loading animals. You pick an animal, put it in you
 | [Wave dots](#wave-dots) | Dots | Waiting for a refresh or sync |
 | [Helix dots](#helix-dots) | Dots | Data processing, fun & playful |
 | [Dot grid wave](#dot-grid-wave) | Dots | Brick/grid placeholders, dashboards |
+| [Ellipsis](#ellipsis) | Dots | Chat, messaging, "hold on" moments |
 | [Arc spinner](#arc-spinner) | Spinner | Classic circular loading |
 | [Material double arc](#material-double-arc) | Spinner | Android/Material look and feel |
 | [Scan sweep](#scan-sweep) | Spinner | Radar/sonar, scanning, searching |
 | [Orbit dots](#orbit-dots) | Spinner | Floaty, lightweight loading |
 | [Orbit ring dots](#orbit-ring-dots) | Spinner | Cosmetic ring, data-heavy load |
+| [Pulsing orb](#pulsing-orb) | Orbs | Ambient loads, hero panels, splash |
+| [Morphing orb](#morphing-orb) | Orbs | Creative waits, brand moments |
+| [Siri orb](#siri-orb) | Orbs | Voice assistants, AI thinking |
+| [Dot orb](#dot-orb) | Orbs | Orbit waits, spatial loading |
+| [Planet orb](#planet-orb) | Orbs | Space motifs, sci-fi waits |
+| [Aura orb](#aura-orb) | Orbs | Gradient waits, brand palettes |
 | [Eyes](#eyes) | Shape | Fun state, "watching" waiting |
 | [Morphing square](#morphing-square) | Shape | Modern brand moments |
 | [Breathing pulse](#breathing-pulse) | Shape | Subtle, gentle "alive" loading |
 | [Equalizer](#equalizer) | Bars & rings | Music, audio, waveform |
 | [Progress ring](#progress-ring) | Bars & rings | Showing exact percent done |
+| [Progress bar](#progress-bar) | Bars & rings | Showing exact percent done, linear |
 | [Indeterminate progress bar](#indeterminate-progress-bar) | Bars & rings | "Doing something, no % yet" bar |
+| [Activity rings](#activity-rings) | Bars & rings | Fitness, health, Apple Watch style |
+| [Waveform](#waveform) | Music | Audio apps, playing states |
+| [Vinyl](#vinyl) | Music | Music apps, retro feels |
+| [Sonar](#sonar) | Music | Audio pulses, location pings |
+| [Music note](#music-note) | Music | Music players, playful waits |
 | [Skeleton shimmer](#skeleton-shimmer) | Skeleton | Placeholder while real content loads |
+| [Skeleton card](#skeleton-card) | Skeleton | Composite card/feed placeholders |
+| [Skeleton list](#skeleton-list) | Skeleton | Chat/inbox/search list placeholders |
 
 ---
 
@@ -70,7 +85,7 @@ export function MyLoader() {
 }
 ```
 
-That's it. Importing the package **automatically registers** all 17 elements for you (it's safe to import in many places — duplicates are skipped). It is also safe on the server (SSR/Next.js): on Node there is no browser, so nothing registers and nothing breaks.
+That's it. Importing the package **automatically registers** all 32 elements for you (it's safe to import in many places — duplicates are skipped). It is also safe on the server (SSR/Next.js): on Node there is no browser, so nothing registers and nothing breaks.
 
 If you prefer to register manually:
 
@@ -98,7 +113,7 @@ Add the package from a CDN (or bundle it) and write the tags directly in your HT
 </div>
 ```
 
-Mix and match any of the 17 tags — see the full list below.
+Mix and match any of the 32 tags — see the full list below.
 
 ---
 
@@ -222,6 +237,12 @@ Every number inside every animation is also a CSS variable. Change how far dots
 | `--lz-eq-min` | Equalizer | Shortest bar height | `0.3` |
 | `--lz-slide-from` | Indeterminate bar | Slider start position | `-100%` |
 | `--lz-slide-to` | Indeterminate bar | Slider end position | `300%` |
+| `--lz-orb-scale` | Pulsing orb | Peak breathe scale | `1.16` |
+| `--lz-orb-fade` | Pulsing orb / dot orb | Mid-breathe opacity (dot orb rests at `0.14`) | `0.88` |
+| `--lz-dot-min` | Dot orb | Resting dot scale | `0.7` |
+| `--lz-wf-min` | Waveform | Resting bar scale | `0.22` |
+| `--lz-sonar-fade` | Sonar | Ring start opacity | `0.9` |
+| `--lz-note-bob` | Music note | Note bob height | `0.35em` |
 
 ---
 
@@ -323,6 +344,23 @@ Variables: `--lz-grid-gap` · `--lz-grid-min` · `--lz-grid-fade`.
 
 ---
 
+### Ellipsis
+
+**What it is:** three periods that appear in a typewriter rhythm. **Good for:** chat, messaging, text queues.
+
+```html
+<lz-ellipsis size="10" color="#0a84ff"></lz-ellipsis>
+```
+
+```tsx
+<Ellipsis size={10} color="#0a84ff" />
+```
+
+Attributes: `size` (default `8`) · `color` · `speed`.
+Variables: `--lz-ellipsis-min` · `--lz-ellipsis-fade`.
+
+---
+
 ### Arc spinner
 
 **What it is:** one spinning "pac-man" ring. The classic. **Good for:** any circular wait.
@@ -408,6 +446,104 @@ Variables: `--lz-dot-size` · `--lz-orbit-fade`.
 
 ---
 
+### Pulsing orb
+
+**What it is:** a glowing gradient orb that breathes in and out. **Good for:** ambient loads, hero panels, app splash screens.
+
+```html
+<lz-pulsing-orb size="64" accent="#ff375f"></lz-pulsing-orb>
+```
+
+```tsx
+<PulsingOrb size={64} accent="#ff375f" />
+```
+
+Attributes: `size` (default `44`) · `accent` (default `#0a84ff`) · `speed`.
+Variables: `--lz-orb-scale` · `--lz-orb-fade`.
+
+---
+
+### Morphing orb
+
+**What it is:** a blob that endlessly morphs its silhouette between rounded shapes. **Good for:** creative waits, brand moments, game loading.
+
+```html
+<lz-morphing-orb size="64" accent="#30d158"></lz-morphing-orb>
+```
+
+```tsx
+<MorphingOrb size={64} accent="#30d158" />
+```
+
+Attributes: `size` (default `44`) · `accent` (default `#0a84ff`) · `speed`.
+
+---
+
+### Siri orb
+
+**What it is:** a Siri-style orb with a multicolored sheen swirling inside a clipped circle. **Good for:** voice assistants, AI "thinking", smart waits.
+
+```html
+<lz-siri-orb size="72" accent="#64d2ff"></lz-siri-orb>
+```
+
+```tsx
+<SiriOrb size={72} accent="#64d2ff" />
+```
+
+Attributes: `size` (default `44`) · `accent` (default `#0a84ff`) · `speed`.
+
+---
+
+### Dot orb
+
+**What it is:** a ring of shimmering dots arranged into an orb silhouette. **Good for:** orbit waits, spatial loading, gaming screens.
+
+```html
+<lz-dot-orb count="12" color="#ff9f0a"></lz-dot-orb>
+```
+
+```tsx
+<DotOrb count={12} color="#ff9f0a" />
+```
+
+Attributes: `size` (default `44`) · `count` (default `8`) · `color` · `speed`.
+Variables: `--lz-dot-min` · `--lz-orb-fade`.
+
+---
+
+### Planet orb
+
+**What it is:** a glowing planet core with small moons orbiting it. **Good for:** space motifs, science apps, sci-fi waits.
+
+```html
+<lz-planet-orb count="3" accent="#bf5af2" color="#64d2ff"></lz-planet-orb>
+```
+
+```tsx
+<PlanetOrb count={3} accent="#bf5af2" color="#64d2ff" />
+```
+
+Attributes: `size` (default `44`) · `accent` (default `#0a84ff`) · `color` · `count` (moons, default `2`) · `speed`.
+
+---
+
+### Aura orb
+
+**What it is:** two tinted orbs counter-rotating in overlapping orbits. **Good for:** gradient waits, brand palettes, hero backgrounds.
+
+```html
+<lz-aura-orb accent="#ff375f" color="#64d2ff"></lz-aura-orb>
+```
+
+```tsx
+<AuraOrb accent="#ff375f" color="#64d2ff" />
+```
+
+Attributes: `size` (default `44`) · `accent` (default `#0a84ff`) · `color` · `speed`.
+
+---
+
 ### Eyes
 
 **What it is:** two cartoon eyes that look side to side and blink. **Good for:** fun apps, "watching" moments, kids' stuff.
@@ -495,6 +631,25 @@ Accessibility: it exposes `role="progressbar"` plus `aria-valuenow/min/max`, and
 
 ---
 
+### Progress bar
+
+**What it is:** a linear bar that fills to a percentage. **Good for:** uploads, downloads, tasks with a known percent. *(Not animated by itself — you drive it with the `percent` attribute.)*
+
+```html
+<lz-progress-bar width="220" height="8" percent="60" color="#0a84ff" track-color="rgba(255,255,255,0.15)"></lz-progress-bar>
+```
+
+```tsx
+<ProgressBar width={220} height={8} percent={60} color="#0a84ff" trackColor="rgba(255,255,255,0.15)" />
+```
+
+Attributes: `width` (default `160`) · `height` (default `6`) · `percent` (default `0`) · `color` (fill) · `track-color` · `speed`.
+Variables: `--lz-track`.
+
+Accessibility: it exposes `role="progressbar"` plus `aria-valuenow/min/max`, and updates them when `percent` changes.
+
+---
+
 ### Indeterminate progress bar
 
 **What it is:** a bar with a slider that slides back and forth. Classic "we're working on it". **Good for:** long unknown tasks.
@@ -512,6 +667,90 @@ Variables: `--lz-accent` · `--lz-surface` · `--lz-slide-from` · `--lz-slide-t
 
 ---
 
+### Activity rings
+
+**What it is:** three Apple Watch-style activity rings spinning at different speeds and directions. **Good for:** fitness apps, health dashboards, workout sync.
+
+```html
+<lz-activity-rings size="64"></lz-activity-rings>
+```
+
+```tsx
+<ActivityRings size={64} />
+```
+
+Attributes: `size` (default `44`) · `accent` (outer, default `#fa114f`) · `color` (middle, default `#30d158`) · `color-weak` (inner, default `#32d7ff`) · `speed`.
+Variables: `--lz-accent` · `--lz-color` · `--lz-color-weak`.
+
+---
+
+### Waveform
+
+**What it is:** a mirrored audio waveform pulsing around a center line. **Good for:** audio apps, playing states, podcast waits.
+
+```html
+<lz-waveform count="15" accent="#bf5af2"></lz-waveform>
+```
+
+```tsx
+<Waveform count={15} accent="#bf5af2" />
+```
+
+Attributes: `size` (height, default `32`) · `count` (bars, default `11`) · `color` · `accent` · `bar-width` (default `4`) · `gap` (default `4`) · `speed`.
+Variables: `--lz-bar-width` · `--lz-gap` · `--lz-wf-min`.
+
+---
+
+### Vinyl
+
+**What it is:** a spinning record with a gently bobbing tonearm. **Good for:** music apps, retro waits, album screens.
+
+```html
+<lz-vinyl accent="#fa114f"></lz-vinyl>
+```
+
+```tsx
+<Vinyl accent="#fa114f" />
+```
+
+Attributes: `size` (default `48`) · `accent` (label/stylus, default `#0a84ff`) · `color` (tonearm) · `speed`.
+
+---
+
+### Sonar
+
+**What it is:** a pulsing core emitting expanding sonar rings. **Good for:** audio pulses, location pings, motion waits.
+
+```html
+<lz-sonar count="4" accent="#30d158"></lz-sonar>
+```
+
+```tsx
+<Sonar count={4} accent="#30d158" />
+```
+
+Attributes: `size` (default `44`) · `count` (rings, default `3`) · `accent` (ring color) · `color` (core) · `speed`.
+Variables: `--lz-sonar-fade`.
+
+---
+
+### Music note
+
+**What it is:** musical note glyphs bobbing in a sing-song rhythm. **Good for:** music players, karaoke, playful waits.
+
+```html
+<lz-music-note count="3" color="#bf5af2"></lz-music-note>
+```
+
+```tsx
+<MusicNote count={3} color="#bf5af2" />
+```
+
+Attributes: `size` (default `32`) · `count` (notes, default `2`) · `color` · `speed`.
+Variables: `--lz-note-bob`.
+
+---
+
 ### Skeleton shimmer
 
 **What it is:** a rounded block with a light that sweeps across. **Good for:** placeholders while real content loads (images, profiles, cards).
@@ -529,6 +768,40 @@ Variables: `--lz-surface` · `--lz-sheen` (sweep light color) · `--lz-radius`
 
 ---
 
+### Skeleton card
+
+**What it is:** a composite card skeleton with an avatar circle and text lines under one shared sheen. **Good for:** profile cards, feed items, user rows.
+
+```html
+<lz-skeleton-card width="240" height="72"></lz-skeleton-card>
+```
+
+```tsx
+<SkeletonCard width={240} height={72} />
+```
+
+Attributes: `width` (default `200`) · `height` (default `64`) · `track-color` · `speed`.
+Variables: `--lz-surface` · `--lz-radius` · `--lz-sheen-from` · `--lz-sheen-to`.
+
+---
+
+### Skeleton list
+
+**What it is:** repeated list rows with avatars and text lines under one shared sheen. **Good for:** chat lists, inbox rows, search results.
+
+```html
+<lz-skeleton-list width="220" rows="5"></lz-skeleton-list>
+```
+
+```tsx
+<SkeletonList width={220} rows={5} />
+```
+
+Attributes: `width` (default `180`) · `rows` (default `4`) · `track-color` · `speed`.
+Variables: `--lz-surface` · `--lz-radius` · `--lz-sheen-from` · `--lz-sheen-to`.
+
+---
+
 ## Accessibility
 
 - Every pattern is announced to screen readers: dots/spinners/bars use `role="status"` with `aria-label="Loading"`.