@noxlovette/material 0.4.8 → 0.5.1

package/dist/components/forms/slider/types.d.ts

@@ -4,7 +4,7 @@ import type { SliderVariants } from './theme.js';
 /**
  * Props for the Slider component.
  */
-export type SliderProps = SliderVariants & Omit<HTMLAttributes<HTMLSpanElement>, 'size' | 'value'> & {
+export type SliderProps = Omit<SliderVariants, 'active'> & Omit<HTMLAttributes<HTMLSpanElement>, 'size' | 'value'> & {
     /**
      * The current value of the slider.
      */

package/dist/components/forms/switch/theme.js

@@ -14,14 +14,14 @@ export const toggle = tv({
             'group-data-[disabled]:cursor-not-allowed',
             'group-data-[disabled]:border-md-sys-color-on-surface/12 group-data-[disabled]:bg-md-sys-color-surface-container-highest',
             'group-data-[state=checked]:group-data-[disabled]:border-transparent group-data-[state=checked]:group-data-[disabled]:bg-md-sys-color-on-surface/12',
-            'transition-colors duration-200'
+            'transition-colors md-sys-motion-effects'
         ].join(' '),
         // Thumb — absolute over track
         handle: [
             'pointer-events-none absolute left-2 top-1/2 flex h-4 w-4 -translate-y-1/2',
             'items-center justify-center rounded-full relative',
             'bg-md-sys-color-outline',
-            'transition-[left,transform,background-color] duration-200 ease-in-out',
+            'transition-[left,transform,background-color] md-sys-motion-fast-spatial',
             // checked: move right + scale up + on-primary color
             'group-data-[state=checked]:left-[1.75rem] group-data-[state=checked]:scale-[1.5] group-data-[state=checked]:bg-md-sys-color-on-primary',
             // disabled
@@ -38,7 +38,7 @@ export const toggle = tv({
         hover: [
             'pointer-events-none absolute left-4 top-1/2 h-12 w-12',
             '-translate-x-1/2 -translate-y-1/2 rounded-full',
-            'transition-[left,background-color] duration-200',
+            'transition-[left,background-color] md-sys-motion-fast-spatial',
             'group-data-[state=checked]:left-9',
             'group-data-[disabled]:hidden',
             'group-hover:bg-md-sys-color-on-surface/8',
@@ -47,7 +47,7 @@ export const toggle = tv({
         // Icon inside thumb - shared base (sized via size="xs" prop on Icon, not here)
         icon: [
             'absolute inset-0 m-auto pointer-events-none flex items-center justify-center',
-            'opacity-0 transition-opacity duration-150 shrink-0'
+            'opacity-0 transition-opacity md-sys-motion-fast-effects shrink-0'
         ].join(' '),
         // Specific icon states - colour matches M3 spec for each thumb background
         iconChecked: [

package/dist/components/forms/textfield/Textfield.svelte

@@ -34,7 +34,7 @@ Text fields allow users to enter and edit text.
     ...restProps
   }: TextfieldProps = $props();
 
-  const cls = $derived(textfield({ disabled, error, variant }));
+  const cls = $derived(textfield({ disabled, error, variant, leadingIcon: !!leadingIconProps }));
 
   const inputProps = $derived({
     id,

package/dist/components/forms/textfield/theme.d.ts

@@ -4,6 +4,7 @@ export declare const textfield: import("tailwind-variants").TVReturnType<{
     variant: {
         filled: {
             base: string;
+            input: string;
             label: string;
         };
         outlined: {
@@ -20,6 +21,9 @@ export declare const textfield: import("tailwind-variants").TVReturnType<{
             fieldset: string;
         };
     };
+    leadingIcon: {
+        true: {};
+    };
     disabled: {
         true: {
             base: string;
@@ -42,6 +46,7 @@ export declare const textfield: import("tailwind-variants").TVReturnType<{
     variant: {
         filled: {
             base: string;
+            input: string;
             label: string;
         };
         outlined: {
@@ -58,6 +63,9 @@ export declare const textfield: import("tailwind-variants").TVReturnType<{
             fieldset: string;
         };
     };
+    leadingIcon: {
+        true: {};
+    };
     disabled: {
         true: {
             base: string;
@@ -80,6 +88,7 @@ export declare const textfield: import("tailwind-variants").TVReturnType<{
     variant: {
         filled: {
             base: string;
+            input: string;
             label: string;
         };
         outlined: {
@@ -96,6 +105,9 @@ export declare const textfield: import("tailwind-variants").TVReturnType<{
             fieldset: string;
         };
     };
+    leadingIcon: {
+        true: {};
+    };
     disabled: {
         true: {
             base: string;

package/dist/components/forms/textfield/theme.js

@@ -4,11 +4,13 @@ export const textfield = tv({
         base: `
       group relative w-full h-14 flex items-center
     `,
+        /* Stretches to the full field height so the label floats relative to the field's top edge,
+           not the input's. */
         inputWrapper: `
-      relative flex-1 px-4
+      relative flex-1 self-stretch flex items-center px-4
     `,
         input: `
-      peer w-full pt-4 bg-transparent outline-none
+      peer w-full bg-transparent outline-none
       md-sys-typescale-body-large text-md-sys-color-on-surface
       disabled:text-md-sys-color-on-surface/38
     `,
@@ -17,7 +19,7 @@ export const textfield = tv({
       md-sys-typescale-body-large
       text-md-sys-color-on-surface-variant
       pointer-events-none
-      transition-[top,font-size,line-height,color,transform] duration-200 ease-in-out
+      transition-[top,left,font-size,line-height,color,transform] md-sys-motion-fast-spatial
 
       peer-focus:text-md-sys-color-primary
     `,
@@ -25,7 +27,7 @@ export const textfield = tv({
       ml-0.5
       text-md-sys-color-error
       group-focus-within:text-md-sys-color-primary
-      transition-colors duration-200
+      transition-colors md-sys-motion-effects
     `,
         leadingIcon: `
       text-md-sys-color-on-surface-variant size-6
@@ -43,9 +45,9 @@ export const textfield = tv({
       text-md-sys-color-on-surface-variant
     `,
         fieldset: `
-      absolute -top-[5px] left-0 right-0 bottom-0 m-0 px-2
+      absolute -top-2 left-0 right-0 bottom-0 m-0 px-3
       pointer-events-none rounded-xs border border-md-sys-color-outline
-      transition-colors duration-150
+      transition-colors md-sys-motion-fast-effects
 
       group-hover:border-md-sys-color-on-surface
       group-focus-within:border-2 group-focus-within:border-md-sys-color-primary
@@ -53,7 +55,7 @@ export const textfield = tv({
         legend: `
       invisible float-none block h-auto max-w-[0.01px] overflow-hidden
       whitespace-nowrap md-sys-typescale-body-small
-      transition-[max-width] duration-150 ease-in-out
+      transition-[max-width] md-sys-motion-fast-spatial
 
       group-focus-within:max-w-full
       group-has-[input:not(:placeholder-shown)]:max-w-full
@@ -69,16 +71,19 @@ export const textfield = tv({
           px-0 bg-md-sys-color-surface-container-highest
           rounded-t-xs state-layer before:rounded-xs hover:before:bg-md-sys-color-on-surface/8
           after:absolute after:bottom-0 after:left-0 after:right-0 after:h-px after:bg-md-sys-color-on-surface-variant
-          after:transition-[height,background-color] after:duration-200
+          after:transition-[height,background-color] after:md-sys-motion-fast-spatial
           hover:after:bg-md-sys-color-on-surface
           focus-within:after:bg-md-sys-color-primary
           focus-within:after:h-[2px]
           disabled:bg-md-sys-color-on-surface/4
           disabled:after:bg-md-sys-color-on-surface/12
         `,
+                /* Room for the label floated inside the container. Outlined labels float into the border
+                   notch instead, so their input stays vertically centered. */
+                input: 'pt-4',
                 label: `
-          peer-focus:top-1.5 peer-focus:md-sys-typescale-body-small peer-focus:-translate-y-1
-          peer-not-placeholder-shown:top-1.5 peer-not-placeholder-shown:md-sys-typescale-body-small peer-not-placeholder-shown:-translate-y-1
+          peer-focus:top-2 peer-focus:md-sys-typescale-body-small peer-focus:translate-y-0
+          peer-not-placeholder-shown:top-2 peer-not-placeholder-shown:md-sys-typescale-body-small peer-not-placeholder-shown:translate-y-0
         `
             },
             outlined: {
@@ -102,6 +107,9 @@ export const textfield = tv({
         `
             }
         },
+        leadingIcon: {
+            true: {}
+        },
         disabled: {
             true: {
                 base: 'cursor-not-allowed opacity-60',
@@ -109,6 +117,18 @@ export const textfield = tv({
             }
         }
     },
+    compoundVariants: [
+        {
+            /* M3: an outlined label floats back to the field's start edge, over the leading icon, into
+               the notch. The wrapper starts after the icon (ml-3 + size-6 = 36px), so -20px puts the
+               label at 16px from the field's edge. */
+            variant: 'outlined',
+            leadingIcon: true,
+            class: {
+                label: 'peer-focus:-left-5 peer-not-placeholder-shown:-left-5'
+            }
+        }
+    ],
     defaultVariants: {
         variant: 'outlined'
     }

package/dist/components/forms/toggle-group/theme.js

@@ -13,7 +13,7 @@ export const toggleGroup = tv({
 });
 export const toggleGroupItem = tv({
     slots: {
-        base: 'layer-container state-layer relative inline-flex min-w-12 flex-1 items-center justify-center gap-2 px-4 md-sys-typescale-label-large text-md-sys-color-on-surface outline-none transition-colors disabled:cursor-not-allowed disabled:opacity-38 [&:not(:last-child)]:border-r [&:not(:last-child)]:border-md-sys-color-outline data-[state=on]:bg-md-sys-color-secondary-container data-[state=on]:text-md-sys-color-on-secondary-container',
+        base: 'layer-container state-layer relative inline-flex min-w-12 flex-1 items-center justify-center gap-2 px-4 md-sys-typescale-label-large text-md-sys-color-on-surface outline-none transition-colors md-sys-motion-fast-effects disabled:cursor-not-allowed disabled:opacity-38 [&:not(:last-child)]:border-r [&:not(:last-child)]:border-md-sys-color-outline data-[state=on]:bg-md-sys-color-secondary-container data-[state=on]:text-md-sys-color-on-secondary-container',
         checkIcon: 'size-[18px] text-[18px]',
         icon: 'size-[18px] text-[18px]'
     }

package/dist/components/forms/tooltip/Tooltip.svelte

@@ -13,7 +13,7 @@ Plain tooltips are used for simple labels, while rich tooltips can contain forma
   import { tooltip } from './theme.js';
   import type { TooltipProps } from './types.js';
   import { Tooltip } from 'bits-ui';
-  import { enterExit, easeEmphasizedDecel, easeEmphasizedAccel } from '../../../animation/index.js';
+  import { enterExit, presence } from '../../../animation/index.js';
 
   let {
     subhead,
@@ -66,43 +66,32 @@ Plain tooltips are used for simple labels, while rich tooltips can contain forma
     {/if}
 
     {#if hasTooltipContent}
-      <Tooltip.Content {...contentProps} forceMount>
+      <Tooltip.Content {...contentProps}>
         {#snippet child({ wrapperProps, props, open })}
-          {#if open}
-            <div {...wrapperProps} class={wrapperProps.class as any}>
-              <div
-                {...props}
-                class={clsx(baseCls, props.class as any)}
-                in:enterExit={{
-                  duration: variant === 'rich' ? 200 : 150,
-                  easing: easeEmphasizedDecel,
-                  mode: 'scale'
-                }}
-                out:enterExit={{
-                  duration: variant === 'rich' ? 150 : 75,
-                  easing: easeEmphasizedAccel,
-                  mode: 'scale'
-                }}
-              >
-                {#if variant === 'rich'}
-                  <Layer />
-                  {#if subhead}
-                    <Title size="small" class={subheadCls()}>
-                      {subhead}
-                    </Title>
-                  {/if}
-                  <Body class={supportingTextCls()}>
-                    {supportingText}
-                  </Body>
-                  {@render children?.()}
-                {:else if supportingText}
-                  <Body class={supportingTextCls()}>
-                    {supportingText}
-                  </Body>
+          <div {...wrapperProps} class={wrapperProps.class as any}>
+            <div
+              {...props}
+              class={clsx(baseCls, props.class as any)}
+              {@attach presence(() => open, enterExit.scale)}
+            >
+              {#if variant === 'rich'}
+                <Layer />
+                {#if subhead}
+                  <Title size="small" class={subheadCls()}>
+                    {subhead}
+                  </Title>
                 {/if}
-              </div>
+                <Body class={supportingTextCls()}>
+                  {supportingText}
+                </Body>
+                {@render children?.()}
+              {:else if supportingText}
+                <Body class={supportingTextCls()}>
+                  {supportingText}
+                </Body>
+              {/if}
             </div>
-          {/if}
+          </div>
         {/snippet}
       </Tooltip.Content>
     {/if}

package/dist/components/nav/breadcrumb/theme.js

@@ -4,7 +4,7 @@ export const breadcrumb = tv({
         base: 'flex',
         list: 'flex flex-wrap items-center gap-1',
         item: 'flex items-center gap-1',
-        link: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant md-sys-state-focus-indicator relative inline-flex min-h-12 items-center rounded-full px-3 transition-colors',
+        link: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant md-sys-state-focus-indicator relative inline-flex min-h-12 items-center rounded-full px-3 transition-colors md-sys-motion-fast-effects',
         text: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant px-1 py-0.5',
         current: 'md-sys-typescale-label-large font-bold px-1 py-0.5',
         separator: 'text-md-sys-color-on-surface-variant inline-flex shrink-0'

package/dist/components/nav/navbar/theme.js

@@ -9,9 +9,9 @@ export const navbar = tv({
 });
 export const navitem = tv({
     slots: {
-        base: 'group relative flex flex-1 flex-col items-center justify-center min-w-0 max-w-[168px] h-full transition-colors',
+        base: 'group relative flex flex-1 flex-col items-center justify-center min-w-0 max-w-[168px] h-full transition-colors md-sys-motion-fast-effects',
         content: 'flex flex-col items-center justify-center gap-1 w-full',
-        iconContainer: 'relative flex items-center justify-center h-8 w-16 rounded-full transition-colors duration-200 ease-in-out',
+        iconContainer: 'relative flex items-center justify-center h-8 w-16 rounded-full transition-colors md-sys-motion-effects',
         icon: 'text-[24px] size-6',
         label: 'md-sys-typescale-label-medium truncate w-full text-center'
     },

package/dist/components/nav/rail/Rail.svelte

@@ -8,7 +8,7 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
 @see https://m3.material.io/components/navigation-rail/overview
 -->
 <script lang="ts">
-  import { clickOutside } from '../../../actions/index.js';
+  import { clickOutside } from '../../../attachments/index.js';
   import clsx from 'clsx';
   import { setContext, untrack } from 'svelte';
   import type { RailProps } from './types';
@@ -62,9 +62,7 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
   class={railBaseClass}
   style={cssVars}
   data-expanded={expanded}
-  use:clickOutside={() => {
-    if (expanded) collapsed = true;
-  }}
+  {@attach expanded && clickOutside(() => (collapsed = true))}
 >
   {#if expandable}
     <ButtonIcon
@@ -91,7 +89,8 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
     pointer-events: none;
     background-color: transparent;
     z-index: -1;
-    transition: opacity 200ms ease;
+    transition: opacity var(--md-sys-motion-duration-effects-spring)
+      var(--md-sys-motion-timing-function-effects-spring);
   }
 
   .rail-scrim[data-expanded='true'] {

package/dist/components/nav/rail/theme.js

@@ -1,9 +1,9 @@
 import { tv } from 'tailwind-variants';
 export const rail = tv({
     slots: {
-        base: 'py-12 hidden bg-md-sys-color-surface-container z-40 flex-col md:flex gap-6 transition-[width,padding,background-color] duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)]',
+        base: 'py-12 hidden bg-md-sys-color-surface-container z-40 flex-col md:flex gap-6 transition-[width,padding,background-color] md-sys-motion-spatial',
         items: 'flex flex-col gap-3 pt-6 scrollbar-none w-full overflow-x-hidden',
-        ghost: 'hidden md:block shrink-0 transition-[width] duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)]',
+        ghost: 'hidden md:block shrink-0 transition-[width] md-sys-motion-spatial',
         scrim: 'hidden md:block lg:hidden inset-0'
     },
     variants: {
@@ -41,11 +41,11 @@ export const rail = tv({
 });
 export const railElement = tv({
     slots: {
-        base: 'group relative z-30 flex w-full transition-all duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)]',
-        content: 'flex items-center min-w-0 rounded-full gap-0.5 py-1.5 transition-all duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)]',
-        iconContainer: 'relative rounded-full items-center justify-center inline-flex transition-all duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)]',
-        icon: 'text-[24px] transition-all duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)]',
-        label: 'transition-all duration-[var(--md-sys-motion-duration-spatial)] ease-[var(--md-sys-motion-timing-function-emphasized)] whitespace-nowrap'
+        base: 'group relative z-30 flex w-full transition-all md-sys-motion-spatial',
+        content: 'flex items-center min-w-0 rounded-full gap-0.5 py-1.5 transition-all md-sys-motion-spatial',
+        iconContainer: 'relative rounded-full items-center justify-center inline-flex transition-all md-sys-motion-spatial',
+        icon: 'text-[24px] transition-all md-sys-motion-spatial',
+        label: 'transition-all md-sys-motion-spatial whitespace-nowrap'
     },
     variants: {
         active: {

package/dist/components/nav/tabs/TabHolder.svelte

@@ -4,15 +4,18 @@ Material 3 Tabs container.
 
 Wraps bits-ui Tabs.Root + Tabs.List and renders a sliding active indicator.
 Use TabContent for content-panel tabs; omit it for navigation (href) tabs.
+Switching panels runs the M3 lateral transition: the new panel pushes the old one out in the
+direction of the selected tab.
 
 @see https://m3.material.io/components/tabs/overview
 -->
 <script lang="ts">
+  import { lateral } from '../../../animation/index.js';
   import { tabHolder } from './theme.js';
   import type { TabHolderProps } from './types.js';
   import Tab from './Tab.svelte';
   import { Tabs } from 'bits-ui';
-  import type { Snippet } from 'svelte';
+  import { tick, type Snippet } from 'svelte';
 
   let {
     items,
@@ -27,9 +30,28 @@ Use TabContent for content-panel tabs; omit it for navigation (href) tabs.
   const idx = $derived(items.findIndex((i) => i.value === value));
   const count = $derived(items.length);
   const { base, bar } = $derived(tabHolder({ rounded }));
+
+  let panels = $state<HTMLElement>();
+
+  /**
+   * Tabs are peers, so switching panels is the M3 lateral transition: the new panel pushes the
+   * old one out toward the side of the newly selected tab. Navigation (href) tabs have no panels
+   * here — the route change is the app's to animate.
+   * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
+   */
+  const select = (next: string) => {
+    const from = idx;
+    const to = items.findIndex((i) => i.value === next);
+    const update = async () => {
+      value = next;
+      await tick();
+    };
+    if (!children || !panels || from === -1 || to === -1 || from === to) return void update();
+    lateral(update, { target: panels, direction: to > from ? 'forward' : 'backward' });
+  };
 </script>
 
-<Tabs.Root bind:value {onValueChange} {activationMode}>
+<Tabs.Root bind:value={() => value, select} {onValueChange} {activationMode}>
   <Tabs.List class={base()}>
     {#each items as item (item)}
       <Tab {...item} {variant} />
@@ -41,5 +63,9 @@ Use TabContent for content-panel tabs; omit it for navigation (href) tabs.
     ></div>
   </Tabs.List>
 
-  {@render children?.()}
+  {#if children}
+    <div bind:this={panels}>
+      {@render children()}
+    </div>
+  {/if}
 </Tabs.Root>

package/dist/components/nav/tabs/TabHolder.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { TabHolderProps } from './types.js';
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
 type $$ComponentProps = TabHolderProps & {
     children?: Snippet;
 };
@@ -8,6 +8,8 @@ type $$ComponentProps = TabHolderProps & {
  *
  * Wraps bits-ui Tabs.Root + Tabs.List and renders a sliding active indicator.
  * Use TabContent for content-panel tabs; omit it for navigation (href) tabs.
+ * Switching panels runs the M3 lateral transition: the new panel pushes the old one out in the
+ * direction of the selected tab.
  *
  * @see https://m3.material.io/components/tabs/overview
  */

package/dist/components/nav/tabs/theme.js

@@ -2,7 +2,7 @@ import { tv } from 'tailwind-variants';
 export const tabHolder = tv({
     slots: {
         base: 'relative flex w-full bg-md-sys-color-surface',
-        bar: 'absolute bottom-0 h-[3px] rounded-t-full bg-md-sys-color-primary transition-transform duration-200 ease-out'
+        bar: 'absolute bottom-0 h-[3px] rounded-t-full bg-md-sys-color-primary transition-transform md-sys-motion-fast-spatial'
     },
     variants: {
         rounded: {

package/dist/components/progress/CircularProgress.svelte

@@ -2,10 +2,18 @@
 @component
 Material 3 Circular Progress Indicator.
 
+Determinate: the arc springs to each new `percent` on the slow effects spring (critically damped,
+so progress never visibly runs backwards), with a gap separating it from the track.
+Indeterminate: the arc's head and tail take turns springing ahead, so it grows, shrinks and
+travels around the circle.
+
 @see https://m3.material.io/components/progress-indicators/overview#circular-progress-indicators
 -->
 <script lang="ts">
   import { Progress } from 'bits-ui';
+  import { animate, type AnimationPlaybackControls } from 'motion';
+  import { springTokens, springTransition } from '../../animation/spring.js';
+  import { SpringValue } from '../../animation/springValue.svelte.js';
 
   let {
     percent,
@@ -20,8 +28,69 @@ Material 3 Circular Progress Indicator.
     thickness?: number;
   } = $props();
 
-  let r = $derived(size / 2 - thickness / 2);
-  let circumference = $derived(Math.PI * r * 2);
+  /* M3: 4dp between the indicator and the track, measured between the rounded caps. */
+  const GAP_PX = 4;
+  /* Indeterminate arc lengths it grows to and shrinks back to. Not M3 values: tune by eye. */
+  const MIN_SWEEP_DEG = 20;
+  const MAX_SWEEP_DEG = 270;
+
+  const r = $derived(size / 2 - thickness / 2);
+  const circumference = $derived(Math.PI * r * 2);
+  /* Round caps overhang each end by half the stroke; the gap sits between those caps. */
+  const gapDeg = $derived((((GAP_PX + thickness) / r) * 180) / Math.PI);
+
+  const shown = new SpringValue(() => percent ?? 0, springTokens.slowEffects);
+
+  let head = $state(0);
+  let tail = $state(0);
+
+  $effect(() => {
+    if (percent != null) return;
+    let running = true;
+    let controls: AnimationPlaybackControls | undefined;
+    const spring = springTransition(springTokens.spatial);
+
+    (async () => {
+      let h = 0;
+      let t = 0;
+      while (running) {
+        controls = animate(h, t + MAX_SWEEP_DEG, { ...spring, onUpdate: (v) => (head = v) });
+        await controls;
+        h = t + MAX_SWEEP_DEG;
+        if (!running) break;
+        controls = animate(t, h - MIN_SWEEP_DEG, { ...spring, onUpdate: (v) => (tail = v) });
+        await controls;
+        t = h - MIN_SWEEP_DEG;
+      }
+    })();
+
+    return () => {
+      running = false;
+      controls?.stop();
+    };
+  });
+
+  /** An arc from `fromDeg`, `sweepDeg` long, as stroke-dash values (0° = 12 o'clock). */
+  const arc = (fromDeg: number, sweepDeg: number) => ({
+    dasharray: `${(Math.max(0, sweepDeg) / 360) * circumference} ${circumference}`,
+    dashoffset: (-(fromDeg % 360) / 360) * circumference,
+    // A zero-length dash with round caps still paints a dot.
+    opacity: sweepDeg > 0.5 ? 1 : 0
+  });
+
+  const from = $derived(percent != null ? 0 : tail);
+  const sweep = $derived(percent != null ? (shown.current / 100) * 360 : head - tail);
+
+  const indicator = $derived(arc(from, sweep));
+  /* The track fills the rest of the circle, keeping a gap either side of the indicator. M3 draws
+     no track while indeterminate. */
+  const track = $derived(
+    percent == null
+      ? arc(0, 0)
+      : indicator.opacity
+        ? arc(from + sweep + gapDeg, 360 - sweep - gapDeg * 2)
+        : arc(0, 360)
+  );
 </script>
 
 <Progress.Root value={percent ?? null} max={100} data-cy="m3-circular-progress">
@@ -40,6 +109,10 @@ Material 3 Circular Progress Indicator.
         {r}
         stroke="var(--color-md-sys-color-secondary-container)"
         stroke-width={thickness}
+        stroke-dasharray={track.dasharray}
+        stroke-dashoffset={track.dashoffset}
+        opacity={track.opacity}
+        stroke-linecap="round"
         fill="none"
       />
       <circle
@@ -48,8 +121,9 @@ Material 3 Circular Progress Indicator.
         {r}
         stroke="var(--color-md-sys-color-primary)"
         stroke-width={thickness}
-        stroke-dasharray="{circumference} {circumference}"
-        stroke-dashoffset={(percent != null ? (percent / -100) * circumference : 0) + circumference}
+        stroke-dasharray={indicator.dasharray}
+        stroke-dashoffset={indicator.dashoffset}
+        opacity={indicator.opacity}
         stroke-linecap="round"
         fill="none"
       />

package/dist/components/progress/CircularProgress.svelte.d.ts

@@ -9,6 +9,11 @@ type $$ComponentProps = {
 /**
  * Material 3 Circular Progress Indicator.
  *
+ * Determinate: the arc springs to each new `percent` on the slow effects spring (critically damped,
+ * so progress never visibly runs backwards), with a gap separating it from the track.
+ * Indeterminate: the arc's head and tail take turns springing ahead, so it grows, shrinks and
+ * travels around the circle.
+ *
  * @see https://m3.material.io/components/progress-indicators/overview#circular-progress-indicators
  */
 declare const CircularProgress: import("svelte").Component<$$ComponentProps, {}, "">;