caraxes

Vue 3 utility library — composables first, thin presentational components on top, in the spirit of VueUse.

Architecture

src/
  components/                    — presentational components built on the composables
    ThinkingOrb/                 — the connecting loader (component + geometry engine)
  composables/                   — reusable reactive utilities, one file each
    useRafFn                     — shared rAF loop (all instances stay in phase)
    useElementVisibility         — IntersectionObserver → reactive visibility
    useDocumentVisibility        — reactive document.visibilityState
    usePreferredReducedMotion    — live prefers-reduced-motion

Single package with tree-shakeable subpath exports: caraxes, caraxes/components, caraxes/composables. When independent versioning is needed, the same folders become packages/* in a pnpm workspace (VueUse's layout) — no code changes required.

Install

npm install caraxes

Usage

Component

<script setup lang="ts">
import { ThinkingOrb } from 'caraxes';
</script>

<template>
  <ThinkingOrb state="connecting" :size="64" color="#818cf8" />
</template>

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | state | 'connecting' | 'connecting' | Only the connecting animation ships. | | size | 64 \| 20 | 64 | Two tuned presets — separate designs, not a scale factor. | | color | string (hex) | #6366f1 | Loader color; depth shading becomes opacity. |

Composables

import { useRafFn } from 'caraxes/composables';

const { isActive, start, stop } = useRafFn(() => console.log('tick'));

Each composable cleans up automatically with its effect scope, is SSR-safe, and returns plain refs.

Behavior

• Auto-pauses offscreen (useElementVisibility) and on hidden tabs (useDocumentVisibility); resumes in phase via the shared useRafFn clock.
• prefers-reduced-motion: reduce renders one static frame — no animation.
• role="img" with aria-label="Connecting…" out of the box.
• Device-pixel-ratio capped at 2. class, style and other attributes fall through to the canvas.

Development

npm run dev       # demo at localhost:5177
npm run check     # geometry parity self-check
npm run build     # library build + types

License

MIT