@marianmeres/stuic 3.165.0 → 3.166.0

package/API.md

@@ -582,11 +582,13 @@ Closeable message banner with intent styling.
 
 #### `Progress`
 
-Progress bar.
+Progress bar or circle.
 
-| Prop    | Type     | Default | Description              |
-| ------- | -------- | ------- | ------------------------ |
-| `value` | `number` | `0`     | Current progress (0-100) |
+| Prop       | Type                | Default | Description                       |
+| ---------- | ------------------- | ------- | --------------------------------- |
+| `progress` | `number`            | `0`     | Current progress (0-100, clamped) |
+| `type`     | `"bar" \| "circle"` | `"bar"` | Rendering variant                 |
+| `classBar` | `string`            | -       | Classes for the inner fill (bar)  |
 
 #### `Spinner`
 
@@ -1206,12 +1208,26 @@ Responsive wrapper around Book that intelligently switches between book mode (du
 
 #### `Circle`
 
-SVG-based circular progress indicator with configurable stroke width and rotation.
+SVG-based circular progress indicator (a Svelte wrapper around the [`svgCircle`](#svgcircleoptions)
+utility). The svg fills its container over a fixed `100x100` viewBox, so the container
+sets the size and `strokeWidth` is in viewBox units. The stroke is `currentColor`.
+
+| Prop                    | Type      | Default | Description                                                      |
+| ----------------------- | --------- | ------- | ---------------------------------------------------------------- |
+| `completeness`          | `number`  | `1`     | Progress from 0 to 1 (clamped)                                   |
+| `strokeWidth`           | `number`  | `10`    | Stroke width in viewBox units (radius = `50 - strokeWidth / 2`)  |
+| `strokeWidthRatio`      | `number`  | `0`     | Caps `strokeWidth` at this fraction of the radius (`0` = no cap) |
+| `bgStrokeColor`         | `string`  | -       | CSS color of the background ring behind the arc                  |
+| `roundedEdges`          | `boolean` | `true`  | Rounded (vs butt) stroke line caps                               |
+| `rotate`                | `number`  | `0`     | Rotation in degrees (arc starts at 3 o'clock; `-90` = top)       |
+| `animateCompletenessMs` | `number`  | `0`     | CSS transition duration on `stroke-dashoffset` (ms)              |
+| `class` / `style`       | `string`  | -       | Container div class / inline style                               |
+| `circleClass`           | `string`  | -       | Classes for the `<svg>` element                                  |
+| `circleStyle`           | `string`  | -       | Inline styles for the `<circle>` element                         |
 
-| Prop          | Type     | Default | Description            |
-| ------------- | -------- | ------- | ---------------------- |
-| `value`       | `number` | `0`     | Progress value (0-100) |
-| `strokeWidth` | `number` | `8`     | Stroke width           |
+```svelte
+<Circle completeness={0.75} rotate={-90} bgStrokeColor="#e5e5e5" class="size-16" />
+```
 
 #### `H`
 
@@ -1935,9 +1951,48 @@ Generate deterministic avatar colors from a name string.
 
 HSL color generation.
 
-#### `svgCircle(radius, strokeWidth)`
+#### `svgCircle(options?)`
+
+Build an SVG ring as a plain DOM node, with setters to update it in place. Framework
+agnostic - it returns the element, mounting it is up to the caller. Used by `Circle` and
+`Progress` internally.
+
+The svg is `width/height: 100%` over a fixed `100x100` viewBox, so the container decides
+the rendered size; `strokeWidth` is in viewBox units and the radius is derived from it
+(`50 - strokeWidth / 2`).
+
+**Options** (all optional):
+
+| Option             | Type      | Default | Description                                                      |
+| ------------------ | --------- | ------- | ---------------------------------------------------------------- |
+| `completeness`     | `number`  | `1`     | Arc length from 0 to 1 (clamped)                                 |
+| `strokeWidth`      | `number`  | `10`    | Stroke width in viewBox units                                    |
+| `strokeWidthRatio` | `number`  | `0`     | Caps `strokeWidth` at this fraction of the radius (`0` = no cap) |
+| `rotate`           | `number`  | `0`     | Rotation in degrees, modulo 360 (arc starts at 3 o'clock)        |
+| `roundedEdges`     | `boolean` | `true`  | Rounded (vs butt) line caps                                      |
+| `bgStrokeColor`    | `string`  | -       | CSS color of a full background ring behind the arc               |
+| `class`            | `string`  | -       | Classes for the `<svg>` element                                  |
+| `circleStyle`      | `string`  | -       | Inline styles for the `<circle>` element                         |
+| `radius`           | `number`  | -       | Currently ignored (derived from the viewBox and stroke width)    |
 
-Generate SVG circle path data.
+**Returns:** `{ svg: SVGSVGElement, setCompleteness(v: number): void, setRotate(deg: number): void }`
+
+The setters mutate the existing element - reach for them instead of rebuilding when only
+the progress or rotation changes.
+
+```ts
+import { svgCircle } from "@marianmeres/stuic";
+
+const { svg, setCompleteness } = svgCircle({
+	completeness: 0.75,
+	strokeWidth: 8,
+	rotate: -90,
+	bgStrokeColor: "#e5e5e5",
+});
+container.appendChild(svg);
+
+setCompleteness(0.9); // no rebuild
+```
 
 #### `oscillate(min, max, step)`
 

package/dist/components/Circle/Circle.svelte

@@ -1,5 +1,24 @@
+<script lang="ts" module>
+	import type { SvgCircleOptions } from "../../utils/svg-circle.js";
+
+	export interface Props extends Partial<SvgCircleOptions> {
+		/** Inline styles for the container element */
+		style?: string;
+		/**
+		 * CSS classes for the `<svg>` element (forwarded to the helper's `class`
+		 * option). Since the stroke is `currentColor`, a text color utility here
+		 * colors the ring.
+		 */
+		circleClass?: string;
+		/** Inline styles for the `<circle>` element */
+		circleStyle?: string;
+		/** Transition duration in ms on the stroke-dashoffset */
+		animateCompletenessMs?: number;
+	}
+</script>
+
 <script lang="ts">
-	import { svgCircle, type SvgCircleOptions } from "../../utils/svg-circle.js";
+	import { svgCircle } from "../../utils/svg-circle.js";
 	import { twMerge } from "../../utils/tw-merge.js";
 
 	let {
@@ -14,13 +33,7 @@
 		circleClass,
 		circleStyle = "",
 		animateCompletenessMs = 0,
-	}: Partial<SvgCircleOptions> & {
-		style?: string;
-		circleClass?: string;
-		circleStyle?: string;
-		// transition duration in ms on the stroke-dashoffset
-		animateCompletenessMs?: number;
-	} = $props();
+	}: Props = $props();
 
 	let container: HTMLDivElement = $state()!;
 
@@ -42,10 +55,12 @@
 	);
 
 	$effect(() => {
-		container.appendChild(circle.svg);
-		return () => {
-			circle.svg.remove();
-		};
+		// Capture the current instance: `circle` is a derived, so reading it again in the
+		// teardown would resolve to the freshly rebuilt svg and leave the previous node
+		// behind (stacking one <svg> per structural prop change).
+		const { svg } = circle;
+		container.appendChild(svg);
+		return () => svg.remove();
 	});
 
 	$effect(() => {

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

@@ -1,10 +1,18 @@
-import { type SvgCircleOptions } from "../../utils/svg-circle.js";
-type $$ComponentProps = Partial<SvgCircleOptions> & {
+import type { SvgCircleOptions } from "../../utils/svg-circle.js";
+export interface Props extends Partial<SvgCircleOptions> {
+    /** Inline styles for the container element */
     style?: string;
+    /**
+     * CSS classes for the `<svg>` element (forwarded to the helper's `class`
+     * option). Since the stroke is `currentColor`, a text color utility here
+     * colors the ring.
+     */
     circleClass?: string;
+    /** Inline styles for the `<circle>` element */
     circleStyle?: string;
+    /** Transition duration in ms on the stroke-dashoffset */
     animateCompletenessMs?: number;
-};
-declare const Circle: import("svelte").Component<$$ComponentProps, {}, "">;
+}
+declare const Circle: import("svelte").Component<Props, {}, "">;
 type Circle = ReturnType<typeof Circle>;
 export default Circle;

package/dist/components/Circle/README.md

@@ -1,22 +1,31 @@
 # Circle
 
-An SVG circle progress indicator with configurable stroke, rotation, and animated transitions.
+An SVG circle progress indicator with configurable stroke, rotation, and animated
+transitions. A thin Svelte wrapper around the [`svgCircle`](../../utils/svg-circle.ts)
+utility.
+
+The svg is rendered at `width/height: 100%` over a fixed `100x100` viewBox, so **the
+container decides the size** (default `size-6`) and `strokeWidth` is expressed in viewBox
+units - i.e. it scales with the box. The stroke defaults to `currentColor`.
 
 ## Props
 
-| Prop                    | Type      | Default | Description                                   |
-| ----------------------- | --------- | ------- | --------------------------------------------- |
-| `completeness`          | `number`  | `1`     | Progress value from 0 to 1                    |
-| `strokeWidth`           | `number`  | `10`    | Stroke width in SVG units                     |
-| `bgStrokeColor`         | `string`  | -       | Background circle stroke color                |
-| `roundedEdges`          | `boolean` | `true`  | Use rounded stroke line caps                  |
-| `rotate`                | `number`  | `0`     | Rotation in degrees                           |
-| `strokeWidthRatio`      | `number`  | `0`     | Ratio for background stroke width             |
-| `animateCompletenessMs` | `number`  | `0`     | Transition duration for progress changes (ms) |
-| `class`                 | `string`  | -       | CSS for container div                         |
-| `style`                 | `string`  | -       | Inline styles for container                   |
-| `circleClass`           | `string`  | -       | CSS for SVG circle element                    |
-| `circleStyle`           | `string`  | -       | Inline styles for circle                      |
+| Prop                    | Type      | Default | Description                                                            |
+| ----------------------- | --------- | ------- | ---------------------------------------------------------------------- |
+| `completeness`          | `number`  | `1`     | Progress from 0 to 1 (clamped)                                         |
+| `strokeWidth`           | `number`  | `10`    | Stroke width in viewBox units (radius = `50 - strokeWidth / 2`)        |
+| `strokeWidthRatio`      | `number`  | `0`     | Caps `strokeWidth` at this fraction of the radius; `0` means no cap    |
+| `bgStrokeColor`         | `string`  | -       | Any CSS color; adds a full background ring behind the arc              |
+| `roundedEdges`          | `boolean` | `true`  | Rounded (vs butt) stroke line caps                                     |
+| `rotate`                | `number`  | `0`     | Rotation in degrees; the arc starts at 3 o'clock, so use `-90` for top |
+| `animateCompletenessMs` | `number`  | `0`     | CSS transition duration on `stroke-dashoffset` (ms)                    |
+| `class`                 | `string`  | -       | CSS classes for the container div                                      |
+| `style`                 | `string`  | -       | Inline styles for the container div                                    |
+| `circleClass`           | `string`  | -       | CSS classes for the `<svg>` element                                    |
+| `circleStyle`           | `string`  | -       | Inline styles for the `<circle>` element                               |
+
+`completeness` and `rotate` are applied through the helper's setters, so changing them
+only rewrites two attributes. Every other prop rebuilds the svg.
 
 ## Usage
 
@@ -24,17 +33,17 @@ An SVG circle progress indicator with configurable stroke, rotation, and animate
 
 ```svelte
 <script lang="ts">
-	import { Circle } from "stuic";
+	import { Circle } from "@marianmeres/stuic";
 </script>
 
-<Circle completeness={0.75} class="size-16" />
+<Circle completeness={0.75} rotate={-90} class="size-16" />
 ```
 
 ### Animated Progress
 
 ```svelte
 <script lang="ts">
-	import { Circle } from "stuic";
+	import { Circle } from "@marianmeres/stuic";
 
 	let progress = $state(0);
 
@@ -54,13 +63,40 @@ An SVG circle progress indicator with configurable stroke, rotation, and animate
 
 ### Custom Styling
 
+The ring's stroke is `currentColor`, so a text color on the container (or on the svg via
+`circleClass`) colors it. To set the stroke directly, use `circleStyle` - it lands on the
+`<circle>` element, which is the only place that beats the `stroke="currentColor"`
+presentation attribute.
+
 ```svelte
+<!-- via currentColor -->
 <Circle
 	completeness={0.5}
 	strokeWidth={8}
 	rotate={-90}
 	bgStrokeColor="rgba(0,0,0,0.1)"
+	class="size-24 text-blue-500"
+/>
+
+<!-- or explicitly on the circle element -->
+<Circle
+	completeness={0.5}
+	rotate={-90}
 	class="size-24"
-	circleClass="stroke-blue-500"
+	circleStyle="stroke: var(--stuic-color-primary);"
 />
 ```
+
+### Content Inside the Ring
+
+```svelte
+<div class="relative size-24">
+	<Circle
+		completeness={0.62}
+		rotate={-90}
+		bgStrokeColor="#e5e5e5"
+		class="absolute inset-0"
+	/>
+	<div class="absolute inset-0 flex items-center justify-center">62%</div>
+</div>
+```

package/dist/components/Circle/index.d.ts

@@ -0,0 +1 @@
+export { default as Circle, type Props as CircleProps } from "./Circle.svelte";

package/dist/components/Circle/index.js

@@ -0,0 +1 @@
+export { default as Circle } from "./Circle.svelte";

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from "./components/Cart/index.js";
 export * from "./components/Card/index.js";
 export * from "./components/Carousel/index.js";
 export * from "./components/Checkout/index.js";
+export * from "./components/Circle/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";

package/dist/index.js

@@ -36,6 +36,7 @@ export * from "./components/Cart/index.js";
 export * from "./components/Card/index.js";
 export * from "./components/Carousel/index.js";
 export * from "./components/Checkout/index.js";
+export * from "./components/Circle/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";

package/docs/domains/utils.md

@@ -110,7 +110,7 @@ const search = debounce((query: string) => {
 | `colors`       | Color manipulation              |
 | `avatarColors` | Deterministic avatar colors     |
 | `paint`        | HSL color generation            |
-| `svgCircle`    | SVG circle path                 |
+| `svgCircle`    | SVG progress ring (DOM node)    |
 | `oscillate`    | Value oscillation for animation |
 
 ### Example: Class Merging

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.165.0",
+	"version": "3.166.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",