# @stackline/loading-core

> Framework-agnostic TypeScript loading toolkit with spinners, overlays, skeletons, shimmer loaders, and smart anti-flicker behavior.

[![npm version](https://img.shields.io/npm/v/@stackline/loading-core.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/loading-core)
[![license](https://img.shields.io/npm/l/@stackline/loading-core.svg?style=flat-square)](https://github.com/alexandroit/loading)
[![GitHub repository](https://img.shields.io/badge/GitHub-repository-181717?style=flat-square&logo=github)](https://github.com/alexandroit/loading)
[![Docs](https://img.shields.io/badge/docs-alexandro.net-0f766e?style=flat-square)](https://alexandro.net/docs/vanilla/loading/)
[![Reddit community](https://img.shields.io/badge/community-r%2FStackline-ff4500?style=flat-square&logo=reddit&logoColor=white)](https://www.reddit.com/r/Stackline/)

**[Documentation](https://alexandro.net/docs/vanilla/loading/)** | **[npm](https://www.npmjs.com/package/@stackline/loading-core)** | **[Issues](https://github.com/alexandroit/loading/issues)** | **[Repository](https://github.com/alexandroit/loading)**

**Current package version:** `1.0.4`

---

## Why this package?

`@stackline/loading-core` is maintained as part of the Stackline package collection.

## Compatibility

| Item | Value |
| :--- | :--- |
| Package | `@stackline/loading-core@1.0.4` |
| API target | `See the package-specific API reference` |
| Supported Node.js | `See supported framework requirements` |
| License | `MIT` |
| Module type | `module` |
| Main entry | `dist/index.cjs` |
| Module entry | `dist/index.js` |
| Types | `dist/index.d.ts` |
| Runtime dependencies | `none` |

## Installation

```bash
npm install @stackline/loading-core
```

## Usage and API reference

> A maintained **framework-agnostic loading toolkit** for modern web applications, with polished variants, smart anti-flicker behavior, accessible defaults, and a documentation site with a live playground.


**[Documentation & Playground](https://alexandro.net/docs/vanilla/loading/)** | **[npm](https://www.npmjs.com/package/@stackline/loading-core)** | **[GitHub Download](https://github.com/alexandroit/loading/tree/main/downloads)** | **[Issues](https://github.com/alexandroit/loading/issues)** | **[Repository](https://github.com/alexandroit/loading)**

**Latest version:** `1.0.4`

---

## Why this library?

Most loading packages stop at a basic spinner. Real products need more:

- multiple visual styles for cards, buttons, dashboards, tables, modals, and fullscreen states
- anti-flicker behavior so fast requests do not flash awkwardly
- accessible defaults with labels, `role="status"`, `aria-live`, and reduced-motion support
- themeability through CSS variables without bringing a framework wrapper into the core package

`@stackline/loading-core` is built as a DOM-first TypeScript library that stays focused on the core runtime, so future framework wrappers can stay thin and consistent.

Version `1.0.2` preserves that stable runtime, CommonJS type resolution, and declaration compatibility with TypeScript 3.9 while updating package documentation and GitHub release tooling.

## Features

| Feature | Supported |
| :--- | :---: |
| TypeScript-first core library | ✅ |
| Framework-agnostic DOM runtime | ✅ |
| ESM + CJS + bundled types | ✅ |
| 35 built-in loading variants | ✅ |
| Spinner, dots, bars, shimmer, skeleton, geometric, sports, and cosmic styles | ✅ |
| Overlay, fullscreen, inline, and centered modes | ✅ |
| Delay before show | ✅ |
| Minimum visible duration | ✅ |
| Mount, unmount, show, hide, toggle, and destroy lifecycle | ✅ |
| Accessible labels and `aria-live` support | ✅ |
| Reduced-motion support | ✅ |
| CSS variable theming | ✅ |
| Documentation site with live playground | ✅ |
| Variant CSS injected on demand | ✅ |

## Table of Contents

1. [Installation](#installation)
2. [Direct Download](#direct-download)
3. [Quick Start](#quick-start)
4. [API Overview](#api-overview)
5. [Built-in Variants](#built-in-variants)
6. [Smart Loading Behavior](#smart-loading-behavior)
7. [Accessibility and Theming](#accessibility-and-theming)
8. [Documentation and Playground](#documentation-and-playground)
9. [Run Locally](#run-locally)
10. [Security](#security)
11. [Community and Links](#community-and-links)
12. [License](#license)

## Installation

```bash
npm install @stackline/loading-core
```

## Direct Download

If you want to use the library in pure browser JavaScript, download the browser bundle from GitHub:

- [GitHub downloads folder](https://github.com/alexandroit/loading/tree/main/downloads)

The archive includes `loading.browser.js` and exposes `window.StacklineLoading`.

```html
<section id="loader-host" style="min-height: 160px; position: relative;"></section>
<script src="./loading.browser.js"></script>
<script>
  const host = document.getElementById("loader-host");
  const loader = StacklineLoading.createLoader({
    variant: "orbit",
    overlay: true,
    centered: true,
    size: 48,
    label: "Loading analytics"
  });

  loader.mount(host);
  loader.show();
</script>
```

## Quick Start

```ts
import { createLoader } from '@stackline/loading-core';

const panel = document.querySelector('.analytics-panel');

const loader = createLoader({
  variant: 'orbit',
  size: 48,
  color: '#2563eb',
  overlay: true,
  centered: true,
  delay: 150,
  minVisible: 280,
  label: 'Loading analytics'
});

loader.mount(panel);
loader.show();

try {
  await loadAnalytics();
} finally {
  await loader.hide();
  loader.destroy();
}
```

## API Overview

The library is centered around a small public API:

```ts
import {
  createLoader,
  hideLoader,
  hydrateLoaders,
  mountLoader,
  showLoader
} from '@stackline/loading-core';
```

Core runtime capabilities:

- `createLoader(options)` creates a typed loader instance
- `loader.mount(target)` mounts into a container or fullscreen target
- `loader.show()` and `loader.hide()` respect `delay` and `minVisible`
- `loader.update()` lets you change variant, colors, sizing, or mode at runtime
- `loader.destroy()` removes the instance cleanly
- `hydrateLoaders()` enables declarative DOM usage through `data-*` attributes

## Built-in Variants

The package currently ships 35 variants:

- `ring`, `dual-ring`, `segmented-ring`, `arc`, `orbit`, `comet`, `halo`, `radar`
- `astronaut`, `astronaut-to-mars`, `baseball-player`, `football-player`, `galaxy`
- `pulse`, `wave-dots`, `bouncing-dots`, `typing-dots`, `grid-pulse`, `magnetic-dots`, `spiral-dots`, `constellation`
- `equalizer-bars`, `rising-bars`
- `shimmer`, `scan-line`, `liquid-pill`, `ripple-stack`, `minimal-spinner`, `neon-spinner`, `glass-spinner`
- `vortex`, `cube`, `diamond`, `prism`, `skeleton-blocks`

## Smart Loading Behavior

The toolkit is designed for real application behavior, not just decoration.

- `delay` prevents flashing loaders for very fast requests
- `minVisible` avoids abrupt hide/show flicker once the loader appears
- `overlay`, `fullscreen`, `inline`, and `centered` cover common product layouts
- runtime mounting makes it easy to load cards, sections, buttons, tables, modals, and full pages

Example:

```ts
const loader = createLoader({
  variant: 'ring',
  delay: 180,
  minVisible: 320,
  overlay: true,
  centered: true,
  label: 'Syncing dashboard'
});
```

## Accessibility and Theming

Accessibility is part of the default behavior:

- `role="status"` and `aria-live` support
- optional visible labels
- `label: ''` for compact cases where visible text should be removed
- reduced-motion support via `prefers-reduced-motion`

Theming is handled with CSS variables and exported theme tokens, so branded overrides stay straightforward.

## Documentation and Playground

The docs site includes:

- installation and quick start guides
- API reference
- variants gallery
- theming and accessibility guides
- overlay, button, fullscreen, and container loading examples
- delay and minimum visibility guidance
- a live playground for variant, size, speed, color, and behavior testing

Docs: `https://alexandro.net/docs/vanilla/loading/`

## Run Locally

```bash
npm install
npm run dev
```

Production build:

```bash
npm run build
```

Verification:

```bash
npm run typecheck
npm test
```

## Security

Report vulnerabilities privately by following [SECURITY.md](SECURITY.md). Do
not disclose exploit details in a public issue.

## Community and Links

- [Stackline website](https://alexandro.net/)
- [GitHub projects](https://github.com/alexandroit)
- [npm packages](https://www.npmjs.com/~alex360qc)
- [Reddit community — r/Stackline](https://www.reddit.com/r/Stackline/)
- [Maintainer LinkedIn](https://www.linkedin.com/in/aleinfo/)

Use the repository's issue tracker for reproducible bugs and feature requests.
Join r/Stackline to share examples, ask usage questions, and discuss releases.

## License

MIT

## Credits and original authors

- Alexandro Marques.
- Copyright (c) 2026 Alexandro Marques.
- Stackline maintenance: [Alexandro Paixao Marques](https://www.linkedin.com/in/aleinfo/) and [Stackline contributors](https://github.com/alexandroit).

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

## Community and Links

- [Stackline website](https://alexandro.net/)
- [GitHub projects](https://github.com/alexandroit)
- [npm packages](https://www.npmjs.com/~alex360qc)
- [Reddit community — r/Stackline](https://www.reddit.com/r/Stackline/)
- [Maintainer LinkedIn](https://www.linkedin.com/in/aleinfo/)

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.