loading-state-zoo 0.2.0 → 0.4.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**.
+**30 loading patterns, one tiny package.** Dots, spinners, orbs, AI, 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,31 @@ 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 |
+| [Sonar](#sonar) | Spinner | Radar pings, location detection |
+| [iOS 27 orb](#ios-27-orb) | Orbs | Voice assistants, AI thinking, holographic waits |
+| [AI orb](#ai-orb) | AI | AI assistants, generative waits |
+| [AI thinking](#ai-thinking) | AI | Chat completions, waiting on answers |
+| [AI neural](#ai-neural) | AI | Neural nets, model training |
 | [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 |
+| [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 +83,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 30 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 +111,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 30 tags — see the full list below.
 
 ---
 
@@ -222,6 +235,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-ios-fade` | iOS 27 orb | Resting dot opacity | `0.2` |
+| `--lz-ios-min` | iOS 27 orb | Resting dot scale | `0.5` |
+| `--lz-ios-peak` | iOS 27 orb | Glowing dot scale | `1.25` |
+| `--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 +342,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.
@@ -359,7 +395,7 @@ Variables: `--lz-stroke` · `--lz-color-weak`.
 
 ### Scan sweep
 
-**What it is:** concentric rings with a sweeping beam — like radar. **Good for:** scanning, searching, syncing data.
+**What it is:** concentric rings with crosshair ticks, a counter-rotating dial and a sweeping beam — like a radar. **Good for:** scanning, searching, syncing data.
 
 ```html
 <lz-scan-sweep size="64" color="#30d158"></lz-scan-sweep>
@@ -408,6 +444,73 @@ Variables: `--lz-dot-size` · `--lz-orbit-fade`.
 
 ---
 
+### iOS 27 orb
+
+**What it is:** an orb of 27 dots where a bright glow travels from the dot being "touched" to the next, spiraling inward like an iOS listening animation. **Good for:** voice assistants, AI thinking, holographic waits.
+
+```html
+<lz-ios-27-orb size="64" accent="#64d2ff" color="#bf5af2"></lz-ios-27-orb>
+```
+
+```tsx
+<Ios27Orb size={64} accent="#64d2ff" color="#bf5af2" />
+```
+
+Attributes: `size` (default `44`) · `accent` (warm pole hue, default `#0a84ff`) · `color` (cool pole hue, default `#f5f5f7`) · `speed`.
+Variables: `--lz-ios-fade` · `--lz-ios-min` · `--lz-ios-peak`.
+
+---
+
+### AI orb
+
+**What it is:** a breathing gradient sphere with an orbiting light dot and twinkling sparkles. **Good for:** AI assistants, generative waits, "smart" ready states.
+
+```html
+<lz-ai-orb size="64" accent="#bf5af2"></lz-ai-orb>
+```
+
+```tsx
+<AiOrb size={64} accent="#bf5af2" />
+```
+
+Attributes: `size` (default `44`) · `accent` (default `#0a84ff`) · `color` (sparkles) · `speed`.
+
+---
+
+### AI thinking
+
+**What it is:** a rounded thinking field with typing dots wrapped in a rotating accent ring. **Good for:** chat completions, AI replies, waiting on answers.
+
+```html
+<lz-ai-thinking size="44" accent="#30d158"></lz-ai-thinking>
+```
+
+```tsx
+<AiThinking size={44} accent="#30d158" />
+```
+
+Attributes: `size` (default `40`) · `accent` (default `#0a84ff`) · `color` (typing dots) · `speed`.
+Variables: `--lz-surface` (field background).
+
+---
+
+### AI neural
+
+**What it is:** a grid of dots pulsing like an artificial neural network with a diagonal activation wave. **Good for:** neural nets, model training, data pipelines.
+
+```html
+<lz-ai-neural rows="4" cols="7" accent="#fa114f"></lz-ai-neural>
+```
+
+```tsx
+<AiNeural rows={4} cols={7} accent="#fa114f" />
+```
+
+Attributes: `size` (default `6`) · `rows` (default `3`) · `cols` (default `5`) · `gap` (default `10`) · `accent` (checking neurons) · `color` (resting neurons) · `speed`.
+Variables: `--lz-grid-gap` · `--lz-grid-min` · `--lz-grid-fade`.
+
+---
+
 ### Eyes
 
 **What it is:** two cartoon eyes that look side to side and blink. **Good for:** fun apps, "watching" moments, kids' stuff.
@@ -495,6 +598,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 +634,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 light sheen, label, spindle and 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:** radar pings, location detection, 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:** drawn musical notes with heads, stems and flags 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 +735,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"`.