@marianmeres/stuic 2.66.0 → 3.0.1

package/dist/components/Spinner/README.md

@@ -1,80 +1,192 @@
 # Spinner
 
-A customizable loading spinner with rotating segments. Pure CSS animation with configurable appearance.
+A family of loading spinner components with different visual styles. All spinners inherit color from `currentColor`, making them easy to style with Tailwind text color classes.
 
-## Props
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `Spinner` | Radial bar spinner with fading segments |
+| `SpinnerCircle` | Simple circular border spinner |
+| `SpinnerCircleOscillate` | Circle with oscillating progress animation |
+| `SpinnerUnicode` | Unicode character-based spinner (17+ variants) |
+
+---
+
+## Spinner
+
+Rotating segments that fade in sequence. Pure CSS animation.
+
+### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `duration` | `number` | `750` | One full rotation duration (ms) |
-| `count` | `number` | `8` | Number of segments/hands (3-12) |
-| `thickness` | `"thin" \| "normal" \| "thick"` | `"thick"` | Segment width |
+| `count` | `number` | `8` | Number of segments (3-12 recommended) |
+| `thickness` | `"thin" \| "normal" \| "thick"` | `"normal"` | Segment width |
 | `height` | `"short" \| "normal" \| "tall"` | `"normal"` | Segment length |
-| `direction` | `"cw" \| "ccw"` | `"cw"` | Rotation direction (clockwise/counter-clockwise) |
-| `class` | `string` | - | CSS classes for sizing |
-
-## Usage
+| `direction` | `"cw" \| "ccw"` | `"cw"` | Rotation direction |
+| `duration` | `number` | `750` | Animation duration (ms) |
+| `rounded` | `number` | `2` | Border radius of segments (px) |
+| `class` | `string` | - | Additional CSS classes |
 
-### Basic Spinner
+### Usage
 
 ```svelte
-<script lang="ts">
-  import { Spinner } from 'stuic';
-</script>
-
 <Spinner />
+<Spinner thickness="thin" count={12} />
+<Spinner class="text-blue-500" direction="ccw" />
 ```
 
-### Different Sizes
+---
+
+## SpinnerCircle
+
+Simple circular spinner using CSS border animation.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `thickness` | `"thin" \| "normal" \| "thick"` | `"normal"` | Border thickness |
+| `direction` | `"cw" \| "ccw"` | `"cw"` | Rotation direction |
+| `duration` | `number` | `750` | Animation duration (ms) |
+| `class` | `string` | - | Additional CSS classes |
+
+### Usage
 
 ```svelte
-<Spinner class="w-4" />
-<Spinner class="w-6" />
-<Spinner class="w-8" />
-<Spinner class="w-12" />
+<SpinnerCircle />
+<SpinnerCircle thickness="thick" class="size-8" />
+<SpinnerCircle class="text-red-500 size-6" direction="ccw" />
 ```
 
-### Customized Appearance
+---
 
-```svelte
-<!-- More segments, thinner -->
-<Spinner count={12} thickness="thin" />
+## SpinnerCircleOscillate
+
+Circle progress indicator with oscillating completeness animation.
+
+### Props
 
-<!-- Fewer segments, thicker, taller -->
-<Spinner count={4} thickness="thick" height="tall" />
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `bgStrokeColor` | `string` | CSS variable | Background stroke color |
+| `strokeWidth` | `number` | - | Stroke width |
+| `noOscillate` | `boolean` | `false` | Disable oscillation (static 66%) |
+| `rotateDuration` | `string` | CSS variable | Rotation duration (e.g., ".75s") |
+| `class` | `string` | - | Additional CSS classes |
+
+### Usage
+
+```svelte
+<SpinnerCircleOscillate />
+<SpinnerCircleOscillate class="text-blue-500 size-8" />
+<SpinnerCircleOscillate noOscillate bgStrokeColor="" />
 ```
 
-### Slower/Faster Animation
+---
+
+## SpinnerUnicode
+
+Text-based spinner cycling through Unicode characters.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `SpinnerUnicodeVariant` | `"braille_bar_dot"` | Built-in animation variant |
+| `speed` | `number` | `100` | Frame duration (ms) |
+| `reversed` | `boolean` | `false` | Reverse animation direction |
+| `frames` | `string[]` | - | Custom frame array |
+| `class` | `string` | - | Additional CSS classes |
+
+### Built-in Variants
+
+`braille_bar`, `braille_bar_dot`, `braille_dot_circle`, `braille_dot_bounce`, `half_circle`, `quarter_circle`, `ascii`, `bar_v`, `bar_h`, `shade`, `arrows`, `arrows2`, `asterix`, `asterix2`, `asterix3`, `asterix4`, `asterix5`
+
+### Usage
 
 ```svelte
-<Spinner duration={500} />  <!-- Faster -->
-<Spinner duration={1500} /> <!-- Slower -->
+<SpinnerUnicode />
+<SpinnerUnicode variant="ascii" />
+<SpinnerUnicode variant="arrows" class="text-green-500" />
+
+<!-- Custom frames -->
+<SpinnerUnicode frames={spinnerCreateBackAndForthCharFrames(5, "■", "□")} />
+```
+
+---
+
+## CSS Customization
+
+All spinners support customization via CSS variables.
+
+### Available Variables
+
+```css
+:root {
+  /* Spinner (radial bars) */
+  --stuic-spinner-opacity: 0.8;
+  --stuic-spinner-fade-end-opacity: 0.12;
+  --stuic-spinner-duration: 750ms;
+
+  /* SpinnerCircle */
+  --stuic-spinner-circle-thickness-thin: 1px;
+  --stuic-spinner-circle-thickness-normal: 2px;
+  --stuic-spinner-circle-thickness-thick: 4px;
+  --stuic-spinner-circle-duration: 750ms;
+
+  /* SpinnerCircleOscillate */
+  --stuic-spinner-circle-oscillate-bg-stroke: var(--stuic-color-border, rgba(0 0 0 / 0.1));
+  --stuic-spinner-circle-oscillate-duration: 0.75s;
+
+  /* SpinnerUnicode */
+  --stuic-spinner-unicode-font-size: var(--text-xl);
+}
 ```
 
-### Counter-Clockwise
+### Global Override
+
+```css
+:root {
+  --stuic-spinner-opacity: 1;
+  --stuic-spinner-circle-thickness-normal: 3px;
+}
+```
+
+### Local Override
 
 ```svelte
-<Spinner direction="ccw" />
+<Spinner style="--stuic-spinner-opacity: 0.5;" />
+<SpinnerCircle style="--stuic-spinner-circle-duration: 500ms;" />
 ```
 
-### With Custom Color
+---
+
+## Color Customization
+
+All spinners use `currentColor`, so apply Tailwind text color classes:
 
 ```svelte
-<Spinner class="w-8 text-blue-500" />
-<Spinner class="w-8 text-green-500" />
+<Spinner class="text-blue-500" />
+<SpinnerCircle class="text-red-600" />
+<SpinnerUnicode class="text-green-500" />
 ```
 
-### Loading Button
+---
+
+## Loading Button Example
 
 ```svelte
 <script lang="ts">
+  import { Button, SpinnerCircle } from 'stuic';
   let loading = $state(false);
 </script>
 
-<button disabled={loading}>
+<Button disabled={loading}>
   {#if loading}
-    <Spinner class="w-4 mr-2" />
+    <SpinnerCircle class="size-4" />
   {/if}
   Submit
-</button>
+</Button>
 ```

package/dist/components/Spinner/Spinner.svelte

@@ -1,9 +1,10 @@
 <script lang="ts" module>
 	export interface Props {
 		class?: string;
+		style?: string;
 		count?: number;
 		thickness?: "thin" | "normal" | "thick";
-		height?: "short" | "normal" | "tall";
+		size?: "sm" | "md" | "lg";
 		direction?: "cw" | "ccw";
 		rounded?: number;
 		duration?: number;
@@ -15,9 +16,10 @@
 
 	let {
 		class: classProp,
+		style: styleProp,
 		count = 8,
 		thickness = "normal",
-		height = "normal",
+		size = "md",
 		direction = "cw",
 		rounded = 2,
 		duration = 750,
@@ -28,29 +30,28 @@
 		normal: 2,
 		thick: 4,
 	};
-	const heightMap: Record<NonNullable<Props["height"]>, number> = {
-		short: 5,
-		normal: 7,
-		tall: 10,
+	const sizeMap: Record<NonNullable<Props["size"]>, number> = {
+		sm: 5,
+		md: 6,
+		lg: 10,
 	};
 
-	const barLength = $derived(heightMap[height]);
+	const barLength = $derived(sizeMap[size]);
 	const barWidth = $derived(thicknessMap[thickness]);
-	const size = $derived(barLength * 3);
-	const center = $derived(size / 2);
+	const containerSize = $derived(barLength * 3);
+	const center = $derived(containerSize / 2);
 	const barHeight = $derived(barLength - 1);
 </script>
 
 <div
-	class={twMerge("spinner opacity-50", classProp)}
-	style:--size="{size}px"
-	style:--duration="{duration}ms"
+	class={twMerge("stuic-spinner", classProp)}
+	style="{styleProp ?? ''}; width: {containerSize}px; height: {containerSize}px; --stuic-spinner-duration: {duration}ms;"
 >
 	{#each Array(count) as _, i}
 		{@const angle = (360 / count) * i}
 		{@const delay = direction === "ccw" ? i / count : (count - i) / count}
 		<span
-			class="bar"
+			class="stuic-spinner-bar"
 			style:width="{barWidth}px"
 			style:height="{barHeight}px"
 			style:border-radius="{rounded}px"
@@ -60,28 +61,3 @@
 		></span>
 	{/each}
 </div>
-
-<style>
-	.spinner {
-		position: relative;
-		width: var(--size);
-		height: var(--size);
-	}
-
-	.bar {
-		position: absolute;
-		left: 50%;
-		top: 0px;
-		background: currentColor;
-		animation: fade var(--duration) linear infinite;
-	}
-
-	@keyframes fade {
-		from {
-			opacity: 1;
-		}
-		to {
-			opacity: 0.12;
-		}
-	}
-</style>

package/dist/components/Spinner/Spinner.svelte.d.ts

@@ -1,8 +1,9 @@
 export interface Props {
     class?: string;
+    style?: string;
     count?: number;
     thickness?: "thin" | "normal" | "thick";
-    height?: "short" | "normal" | "tall";
+    size?: "sm" | "md" | "lg";
     direction?: "cw" | "ccw";
     rounded?: number;
     duration?: number;

package/dist/components/Spinner/SpinnerCircle.svelte

@@ -1,6 +1,7 @@
 <script lang="ts" module>
 	export interface Props {
 		class?: string;
+		style?: string;
 		/** One "loop" duration in ms */
 		duration?: number;
 		/** Border thickness preset */
@@ -15,48 +16,19 @@
 
 	let {
 		class: classProp,
+		style: styleProp,
 		duration = 750,
 		thickness = "normal",
 		direction = "cw",
 	}: Props = $props();
 
 	let _thickness = $derived(
-		"thickness-" +
-			(["normal", "thin", "thick"].includes(thickness) ? thickness : "normal")
+		["normal", "thin", "thick"].includes(thickness) ? thickness : "normal"
 	);
 </script>
 
 <span
-	class={twMerge("stuic-spinner-basic inline-block size-5", _thickness, classProp)}
-	style="animation-duration: {duration}ms; animation-direction: {direction === 'ccw'
-		? 'reverse'
-		: 'normal'};"
+	class={twMerge("stuic-spinner-circle size-4", classProp)}
+	data-thickness={_thickness}
+	style="{styleProp ?? ''}; --stuic-spinner-circle-duration: {duration}ms; animation-direction: {direction === 'ccw' ? 'reverse' : 'normal'};"
 ></span>
-
-<style>
-	.stuic-spinner-basic {
-		box-sizing: border-box;
-		border-radius: 50%;
-		border-style: solid;
-		border-color: currentColor;
-		border-top-color: transparent;
-		animation: spin linear infinite;
-	}
-
-	/* Thickness presets */
-	.stuic-spinner-basic.thickness-thin {
-		border-width: 1px;
-	}
-	.stuic-spinner-basic.thickness-normal {
-		border-width: 2px;
-	}
-	.stuic-spinner-basic.thickness-thick {
-		border-width: 4px;
-	}
-
-	@keyframes spin {
-		to {
-			transform: rotate(360deg);
-		}
-	}
-</style>

package/dist/components/Spinner/SpinnerCircle.svelte.d.ts

@@ -1,5 +1,6 @@
 export interface Props {
     class?: string;
+    style?: string;
     /** One "loop" duration in ms */
     duration?: number;
     /** Border thickness preset */

package/dist/components/Spinner/SpinnerCircleOscillate.svelte

@@ -17,12 +17,17 @@
 
 	let {
 		class: classProp = "",
-		bgStrokeColor = "rgba(0 0 0 / .1)",
+		bgStrokeColor,
 		strokeWidth,
 		noOscillate,
-		rotateDuration = ".75s",
+		rotateDuration,
 	}: Props = $props();
 
+	// Use CSS variable as default when bgStrokeColor is not provided
+	const _bgStrokeColor = $derived(
+		bgStrokeColor ?? "var(--stuic-spinner-circle-oscillate-bg-stroke)"
+	);
+
 	/**
 	 * NOTE: we happen to have 4 distinct values here which effect the overall look and feel...
 	 *  1. the tick frequency
@@ -40,8 +45,8 @@
 <Circle
 	animateCompletenessMs={0}
 	{completeness}
-	class={twMerge("stuic-spinner-circle animate-spin", classProp)}
-	{bgStrokeColor}
+	class={twMerge("stuic-spinner-circle-oscillate", classProp)}
+	bgStrokeColor={_bgStrokeColor}
 	{strokeWidth}
-	style="animation-duration: {rotateDuration}"
+	style={rotateDuration ? `--stuic-spinner-circle-oscillate-duration: ${rotateDuration}` : undefined}
 />

package/dist/components/Spinner/SpinnerUnicode.svelte

@@ -20,6 +20,7 @@
 
 	export interface Props {
 		class?: string;
+		style?: string;
 		speed?: number;
 		variant?: SpinnerUnicodeVariant;
 		reversed?: boolean;
@@ -68,6 +69,7 @@
 
 	let {
 		class: _class = "",
+		style: _style,
 		speed = 100,
 		variant = "braille_bar_dot",
 		reversed = false,
@@ -152,6 +154,6 @@
 	});
 </script>
 
-<span class={twMerge(`inline-block font-mono leading-none text-current text-xl`, _class)}>
+<span class={twMerge("stuic-spinner-unicode", _class)} style={_style}>
 	{_frames[currentFrame]}
 </span>

package/dist/components/Spinner/SpinnerUnicode.svelte.d.ts

@@ -1,6 +1,7 @@
 export type SpinnerUnicodeVariant = "braille_bar" | "braille_bar_dot" | "braille_dot_circle" | "braille_dot_bounce" | "half_circle" | "quarter_circle" | "ascii" | "bar_v" | "bar_h" | "shade" | "arrows" | "arrows2" | "asterix" | "asterix2" | "asterix3" | "asterix4" | "asterix5";
 export interface Props {
     class?: string;
+    style?: string;
     speed?: number;
     variant?: SpinnerUnicodeVariant;
     reversed?: boolean;

package/dist/components/Spinner/index.css

@@ -0,0 +1,104 @@
+:root {
+	/* Spinner (radial bars) */
+	--stuic-spinner-opacity: 0.8;
+	--stuic-spinner-fade-end-opacity: 0.12;
+	--stuic-spinner-duration: 750ms;
+
+	/* SpinnerCircle */
+	--stuic-spinner-circle-thickness-thin: 1px;
+	--stuic-spinner-circle-thickness-normal: 2px;
+	--stuic-spinner-circle-thickness-thick: 4px;
+	--stuic-spinner-circle-duration: 750ms;
+
+	/* SpinnerCircleOscillate */
+	--stuic-spinner-circle-oscillate-bg-stroke: var(
+		--stuic-color-border,
+		rgba(0 0 0 / 0.1)
+	);
+	--stuic-spinner-circle-oscillate-duration: 0.75s;
+
+	/* SpinnerUnicode */
+	--stuic-spinner-unicode-font-size: var(--text-xl);
+}
+
+@layer components {
+	/* ========================================================================
+	   Spinner (radial bars)
+	   ======================================================================== */
+
+	.stuic-spinner {
+		position: relative;
+		opacity: var(--stuic-spinner-opacity);
+	}
+
+	.stuic-spinner-bar {
+		position: absolute;
+		left: 50%;
+		top: 0;
+		background: currentColor;
+		animation: stuic-spinner-fade var(--stuic-spinner-duration) linear infinite;
+	}
+
+	@keyframes stuic-spinner-fade {
+		from {
+			opacity: 1;
+		}
+		to {
+			opacity: var(--stuic-spinner-fade-end-opacity);
+		}
+	}
+
+	/* ========================================================================
+	   SpinnerCircle
+	   ======================================================================== */
+
+	.stuic-spinner-circle {
+		display: inline-block;
+		box-sizing: border-box;
+		border-radius: 50%;
+		border-style: solid;
+		border-color: currentColor;
+		border-top-color: transparent;
+		animation: stuic-spinner-circle-spin linear infinite;
+		animation-duration: var(--stuic-spinner-circle-duration);
+	}
+
+	.stuic-spinner-circle[data-thickness="thin"] {
+		border-width: var(--stuic-spinner-circle-thickness-thin);
+	}
+
+	.stuic-spinner-circle[data-thickness="normal"] {
+		border-width: var(--stuic-spinner-circle-thickness-normal);
+	}
+
+	.stuic-spinner-circle[data-thickness="thick"] {
+		border-width: var(--stuic-spinner-circle-thickness-thick);
+	}
+
+	@keyframes stuic-spinner-circle-spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+
+	/* ========================================================================
+	   SpinnerCircleOscillate
+	   ======================================================================== */
+
+	.stuic-spinner-circle-oscillate {
+		animation: stuic-spinner-circle-spin linear infinite;
+		animation-duration: var(--stuic-spinner-circle-oscillate-duration);
+	}
+
+	/* ========================================================================
+	   SpinnerUnicode
+	   ======================================================================== */
+
+	.stuic-spinner-unicode {
+		display: inline-block;
+		font-family: var(--font-mono);
+		line-height: 1;
+		color: currentColor;
+		font-size: var(--stuic-spinner-unicode-font-size);
+	}
+}