From 30b83213a8d0077c14e3962ead2762ed83ffca3e Mon Sep 17 00:00:00 2001
From: Giamir Buoncristiani <giamir.buoncristiani@gmail.com>
Date: Wed, 28 Jan 2026 16:45:04 +0100
Subject: [PATCH 1/5] feat(vote): extract the vote state logic in an opt in
 svelte module

---
 .../src/components/Vote/Vote.stories.svelte   |  49 +-
 .../src/components/Vote/Vote.svelte           |  61 +-
 .../src/components/Vote/Vote.test.ts          |  86 +--
 .../components/Vote/vote-state.svelte.test.ts | 523 ++++++++++++++++++
 .../src/components/Vote/vote-state.svelte.ts  | 235 ++++++++
 5 files changed, 866 insertions(+), 88 deletions(-)
 create mode 100644 packages/stacks-svelte/src/components/Vote/vote-state.svelte.test.ts
 create mode 100644 packages/stacks-svelte/src/components/Vote/vote-state.svelte.ts

diff --git a/packages/stacks-svelte/src/components/Vote/Vote.stories.svelte b/packages/stacks-svelte/src/components/Vote/Vote.stories.svelte
index f8e4d3aa03..f83720c8d4 100644
--- a/packages/stacks-svelte/src/components/Vote/Vote.stories.svelte
+++ b/packages/stacks-svelte/src/components/Vote/Vote.stories.svelte
@@ -1,6 +1,7 @@
 <script lang="ts" module>
     import { defineMeta } from "@storybook/addon-svelte-csf";
     import Vote, { type Status } from "./Vote.svelte";
+    import { createVoteState } from "./vote-state.svelte";
 
     const VoteStatuses: Status[] = [null, "upvoted", "downvoted"];
 
@@ -17,8 +18,8 @@
 </script>
 
 <Story name="Base">
-    {#snippet template(args)}
-        <Vote {...args} />
+    {#snippet template({ total, ...args })}
+        <Vote total={total ?? 0} {...args} />
     {/snippet}
 </Story>
 
@@ -70,3 +71,47 @@
         </div>
     {/snippet}
 </Story>
+
+<Story name="With State Utility" asChild>
+    {@const voteState = createVoteState({
+        total: 42,
+        upvotes: 50,
+        downvotes: 8,
+        onUpvote: async () => {
+            // Simulate server delay
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            console.log("Upvote sent to server");
+        },
+        onDownvote: async () => {
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            console.log("Downvote sent to server");
+        },
+    })}
+    <div class="d-flex fd-column g16">
+        <Vote {...voteState} />
+        <p class="fs-caption fc-medium">
+            Click the vote buttons - state is managed automatically with
+            optimistic updates
+        </p>
+    </div>
+</Story>
+
+<Story name="With Error Rollback" asChild>
+    {@const voteState = createVoteState({
+        total: 10,
+        onUpvote: async () => {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            throw new Error("Server error - vote rolled back");
+        },
+        onDownvote: async () => {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            throw new Error("Server error - vote rolled back");
+        },
+    })}
+    <div class="d-flex fd-column g16">
+        <Vote {...voteState} />
+        <p class="fs-caption fc-medium">
+            Votes will rollback after 500ms (simulated server error)
+        </p>
+    </div>
+</Story>
diff --git a/packages/stacks-svelte/src/components/Vote/Vote.svelte b/packages/stacks-svelte/src/components/Vote/Vote.svelte
index de3ee00033..0c7febd723 100644
--- a/packages/stacks-svelte/src/components/Vote/Vote.svelte
+++ b/packages/stacks-svelte/src/components/Vote/Vote.svelte
@@ -79,15 +79,13 @@
         i18nExpanded?: string | undefined;
         /**
          * Callback fired when the upvote button is clicked.
-         * Should return a promise that resolves on success.
          */
-        onupvote?: () => Promise<void>;
+        onupvoteclick?: () => void;
 
         /**
          * Callback fired when the downvote button is clicked.
-         * Should return a promise that resolves on success.
          */
-        ondownvote?: () => Promise<void>;
+        ondownvoteclick?: () => void;
 
         /**
          * Additional CSS classes added to the element
@@ -97,8 +95,8 @@
 
     const {
         total,
-        upvotes = undefined,
-        downvotes = undefined,
+        upvotes,
+        downvotes,
         horizontal,
         upvoteOnly = false,
         status = null,
@@ -109,8 +107,8 @@
         i18nDownvoted = "Downvoted",
         i18nExpand = "Show vote details",
         i18nExpanded = "Hide vote details",
-        onupvote = () => Promise.resolve(),
-        ondownvote = () => Promise.resolve(),
+        onupvoteclick = () => {},
+        ondownvoteclick = () => {},
         class: className = "",
     }: Props = $props();
 
@@ -140,39 +138,7 @@
     let expandable = $derived(
         upvotes !== undefined && downvotes !== undefined && !horizontal
     );
-    // svelte-ignore state_referenced_locally
-    // Props are intentionally captured as initial values. The component uses optimistic updates
-    // for vote actions, so local state may temporarily diverge from props during async operations.
-    let currentCount = $state(total || 0);
-    // svelte-ignore state_referenced_locally
-    let currentStatus = $state(status);
     const classes = $derived(getClasses(className, expanded, horizontal));
-
-    async function handleVote(
-        type: "upvoted" | "downvoted",
-        callback: () => Promise<void>
-    ) {
-        const previousCount = currentCount;
-        const previousStatus = currentStatus;
-        const increment = type === "upvoted" ? 1 : -1;
-
-        if (currentStatus === type) {
-            currentStatus = null;
-            currentCount -= increment;
-        } else {
-            currentCount += currentStatus ? increment * 2 : increment;
-            currentStatus = type;
-        }
-
-        try {
-            await callback();
-        } catch {
-            // Revert on failure
-            currentCount = previousCount;
-            currentStatus = previousStatus;
-            // Don't re-throw - the error should be handled by the callback if needed
-        }
-    }
 </script>
 
 {#snippet votes()}
@@ -186,9 +152,7 @@
             <span class="s-vote--upvotes">+{formatCount(upvotes, 1000)}</span>
         {/if}
         <span class="s-vote--total">
-            {currentCount !== 0 || currentStatus !== null
-                ? formatCount(currentCount, 1000)
-                : i18nVote}
+            {total !== 0 ? formatCount(total, 1000) : i18nVote}
         </span>
         {#if downvotes !== undefined}
             <span class="s-vote--downvotes"
@@ -204,8 +168,8 @@
 {/snippet}
 
 <div class={classes}>
-    <button class="s-vote--btn" onclick={() => handleVote("upvoted", onupvote)}>
-        {#if currentStatus === "upvoted"}
+    <button class="s-vote--btn" onclick={onupvoteclick}>
+        {#if status === "upvoted"}
             <Icon src={IconVote16UpFill} />
             <span class="v-visible-sr">{i18nUpvoted}</span>
         {:else}
@@ -218,11 +182,8 @@
     </button>
     {#if !upvoteOnly}
         {@render votes()}
-        <button
-            class="s-vote--btn"
-            onclick={() => handleVote("downvoted", ondownvote)}
-        >
-            {#if currentStatus === "downvoted"}
+        <button class="s-vote--btn" onclick={ondownvoteclick}>
+            {#if status === "downvoted"}
                 <Icon src={IconVote16DownFill} />
                 <span class="v-visible-sr">{i18nDownvoted}</span>
             {:else}
diff --git a/packages/stacks-svelte/src/components/Vote/Vote.test.ts b/packages/stacks-svelte/src/components/Vote/Vote.test.ts
index e4f3ce9359..39a803b846 100644
--- a/packages/stacks-svelte/src/components/Vote/Vote.test.ts
+++ b/packages/stacks-svelte/src/components/Vote/Vote.test.ts
@@ -5,6 +5,7 @@ import userEvent from "@testing-library/user-event";
 import sinon from "sinon";
 
 import Vote from "./Vote.svelte";
+import { createVoteState } from "./vote-state.svelte";
 
 describe("Vote", () => {
     it("should render the vote component", () => {
@@ -88,9 +89,9 @@ describe("Vote", () => {
         expect(svg).to.exist;
     });
 
-    it("should call onupvote handler when upvote button is clicked", async () => {
-        const onupvote = sinon.stub().resolves();
-        render(Vote, { total: 12, onupvote });
+    it("should call onupvoteclick handler when upvote button is clicked", async () => {
+        const onupvoteclick = sinon.stub();
+        render(Vote, { total: 12, onupvoteclick });
 
         const user = userEvent.setup();
         const upvoteBtn = screen.getAllByRole("button")[0];
@@ -98,12 +99,12 @@ describe("Vote", () => {
         await user.click(upvoteBtn);
         await tick();
 
-        expect(onupvote).to.have.been.calledOnce;
+        expect(onupvoteclick).to.have.been.calledOnce;
     });
 
-    it("should call ondownvote handler when downvote button is clicked", async () => {
-        const ondownvote = sinon.stub().resolves();
-        render(Vote, { total: 12, ondownvote });
+    it("should call ondownvoteclick handler when downvote button is clicked", async () => {
+        const ondownvoteclick = sinon.stub();
+        render(Vote, { total: 12, ondownvoteclick });
 
         const user = userEvent.setup();
         const downvoteBtn = screen.getAllByRole("button")[1];
@@ -111,12 +112,13 @@ describe("Vote", () => {
         await user.click(downvoteBtn);
         await tick();
 
-        expect(ondownvote).to.have.been.calledOnce;
+        expect(ondownvoteclick).to.have.been.calledOnce;
     });
 
-    it("should update count when upvoting", async () => {
-        const onupvote = sinon.stub().resolves();
-        render(Vote, { total: 12, onupvote });
+    it("should update count when upvoting with state utility", async () => {
+        const onUpvote = sinon.stub().resolves();
+        const voteState = createVoteState({ total: 12, onUpvote });
+        render(Vote, voteState);
 
         const user = userEvent.setup();
         const upvoteBtn = screen.getAllByRole("button")[0];
@@ -124,12 +126,14 @@ describe("Vote", () => {
         await user.click(upvoteBtn);
         await tick();
 
-        expect(screen.getByText("13")).to.exist;
+        expect(voteState.total).to.equal(13);
+        expect(voteState.status).to.equal("upvoted");
     });
 
-    it("should update count when downvoting", async () => {
-        const ondownvote = sinon.stub().resolves();
-        render(Vote, { total: 12, ondownvote });
+    it("should update count when downvoting with state utility", async () => {
+        const onDownvote = sinon.stub().resolves();
+        const voteState = createVoteState({ total: 12, onDownvote });
+        render(Vote, voteState);
 
         const user = userEvent.setup();
         const downvoteBtn = screen.getAllByRole("button")[1];
@@ -137,12 +141,14 @@ describe("Vote", () => {
         await user.click(downvoteBtn);
         await tick();
 
-        expect(screen.getByText("11")).to.exist;
+        expect(voteState.total).to.equal(11);
+        expect(voteState.status).to.equal("downvoted");
     });
 
-    it("should revert count on error", async () => {
-        const onupvote = sinon.stub().rejects(new Error("Failed"));
-        render(Vote, { total: 12, onupvote });
+    it("should revert count on error with state utility", async () => {
+        const onUpvote = sinon.stub().rejects(new Error("Failed"));
+        const voteState = createVoteState({ total: 12, onUpvote });
+        render(Vote, voteState);
 
         const user = userEvent.setup();
         const upvoteBtn = screen.getAllByRole("button")[0];
@@ -150,12 +156,14 @@ describe("Vote", () => {
         await user.click(upvoteBtn);
         await tick();
 
-        expect(screen.getByText("12")).to.exist;
+        expect(voteState.total).to.equal(12);
+        expect(voteState.status).to.equal(null);
     });
 
-    it("should toggle vote when clicking same button again", async () => {
-        const onupvote = sinon.stub().resolves();
-        render(Vote, { total: 12, onupvote });
+    it("should toggle vote when clicking same button again with state utility", async () => {
+        const onUpvote = sinon.stub().resolves();
+        const voteState = createVoteState({ total: 12, onUpvote });
+        render(Vote, voteState);
 
         const user = userEvent.setup();
         const upvoteBtn = screen.getAllByRole("button")[0];
@@ -163,18 +171,21 @@ describe("Vote", () => {
         // First click - upvote
         await user.click(upvoteBtn);
         await tick();
-        expect(screen.getByText("13")).to.exist;
+        expect(voteState.total).to.equal(13);
+        expect(voteState.status).to.equal("upvoted");
 
         // Second click - remove upvote
         await user.click(upvoteBtn);
         await tick();
-        expect(screen.getByText("12")).to.exist;
+        expect(voteState.total).to.equal(12);
+        expect(voteState.status).to.equal(null);
     });
 
-    it("should switch from upvote to downvote", async () => {
-        const onupvote = sinon.stub().resolves();
-        const ondownvote = sinon.stub().resolves();
-        render(Vote, { total: 12, onupvote, ondownvote });
+    it("should switch from upvote to downvote with state utility", async () => {
+        const onUpvote = sinon.stub().resolves();
+        const onDownvote = sinon.stub().resolves();
+        const voteState = createVoteState({ total: 12, onUpvote, onDownvote });
+        render(Vote, voteState);
 
         const user = userEvent.setup();
         const upvoteBtn = screen.getAllByRole("button")[0];
@@ -183,12 +194,14 @@ describe("Vote", () => {
         // Upvote
         await user.click(upvoteBtn);
         await tick();
-        expect(screen.getByText("13")).to.exist;
+        expect(voteState.total).to.equal(13);
+        expect(voteState.status).to.equal("upvoted");
 
         // Downvote (should change by 2)
         await user.click(downvoteBtn);
         await tick();
-        expect(screen.getByText("11")).to.exist;
+        expect(voteState.total).to.equal(11);
+        expect(voteState.status).to.equal("downvoted");
     });
 
     it("should apply custom class", () => {
@@ -219,9 +232,10 @@ describe("Vote", () => {
         expect(screen.getByText("Expand votes")).to.exist;
     });
 
-    it("should show count instead of 'Vote' text after voting on 0 count", async () => {
-        const onupvote = sinon.stub().resolves();
-        render(Vote, { total: 0, onupvote });
+    it("should show count instead of 'Vote' text after voting on 0 count with state utility", async () => {
+        const onUpvote = sinon.stub().resolves();
+        const voteState = createVoteState({ total: 0, onUpvote });
+        render(Vote, voteState);
 
         const user = userEvent.setup();
         const upvoteBtn = screen.getAllByRole("button")[0];
@@ -229,7 +243,7 @@ describe("Vote", () => {
         await user.click(upvoteBtn);
         await tick();
 
-        expect(screen.getByText("1")).to.exist;
-        expect(screen.queryByText("Vote")).to.not.exist;
+        expect(voteState.total).to.equal(1);
+        expect(voteState.status).to.equal("upvoted");
     });
 });
diff --git a/packages/stacks-svelte/src/components/Vote/vote-state.svelte.test.ts b/packages/stacks-svelte/src/components/Vote/vote-state.svelte.test.ts
new file mode 100644
index 0000000000..029f643a88
--- /dev/null
+++ b/packages/stacks-svelte/src/components/Vote/vote-state.svelte.test.ts
@@ -0,0 +1,523 @@
+import { expect } from "@open-wc/testing";
+import { flushSync } from "svelte";
+import sinon from "sinon";
+
+import { createVoteState } from "./vote-state.svelte";
+
+describe("createVoteState", () => {
+    describe("initialization", () => {
+        it("should initialize with provided total", () => {
+            const state = createVoteState({ total: 42 });
+            expect(state.total).to.equal(42);
+        });
+
+        it("should initialize with provided upvotes and downvotes", () => {
+            const state = createVoteState({
+                total: 20,
+                upvotes: 28,
+                downvotes: 8,
+            });
+            expect(state.total).to.equal(20);
+            expect(state.upvotes).to.equal(28);
+            expect(state.downvotes).to.equal(8);
+        });
+
+        it("should initialize with provided status", () => {
+            const state = createVoteState({ total: 10, status: "upvoted" });
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should default status to null", () => {
+            const state = createVoteState({ total: 10 });
+            expect(state.status).to.equal(null);
+        });
+
+        it("should have undefined upvotes/downvotes when not provided", () => {
+            const state = createVoteState({ total: 10 });
+            expect(state.upvotes).to.be.undefined;
+            expect(state.downvotes).to.be.undefined;
+        });
+    });
+
+    describe("upvote - no prior vote", () => {
+        it("should increment total by 1", async () => {
+            const state = createVoteState({ total: 10 });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+        });
+
+        it("should set status to upvoted", async () => {
+            const state = createVoteState({ total: 10 });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should increment upvotes when provided", async () => {
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+            });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.upvotes).to.equal(16);
+            expect(state.downvotes).to.equal(5);
+        });
+
+        it("should call onUpvote hook", async () => {
+            const onUpvote = sinon.stub().resolves();
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            expect(onUpvote).to.have.been.calledOnce;
+        });
+    });
+
+    describe("upvote - already upvoted (toggle off)", () => {
+        it("should decrement total by 1", async () => {
+            const state = createVoteState({ total: 10, status: "upvoted" });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(9);
+        });
+
+        it("should set status to null", async () => {
+            const state = createVoteState({ total: 10, status: "upvoted" });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.status).to.equal(null);
+        });
+
+        it("should decrement upvotes when provided", async () => {
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                status: "upvoted",
+            });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.upvotes).to.equal(14);
+            expect(state.downvotes).to.equal(5);
+        });
+    });
+
+    describe("upvote - currently downvoted (switch)", () => {
+        it("should increment total by 2", async () => {
+            const state = createVoteState({ total: 10, status: "downvoted" });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(12);
+        });
+
+        it("should set status to upvoted", async () => {
+            const state = createVoteState({ total: 10, status: "downvoted" });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should update upvotes and downvotes when provided", async () => {
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                status: "downvoted",
+            });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.upvotes).to.equal(16);
+            expect(state.downvotes).to.equal(4);
+        });
+    });
+
+    describe("downvote - no prior vote", () => {
+        it("should decrement total by 1", async () => {
+            const state = createVoteState({ total: 10 });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(9);
+        });
+
+        it("should set status to downvoted", async () => {
+            const state = createVoteState({ total: 10 });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.status).to.equal("downvoted");
+        });
+
+        it("should increment downvotes when provided", async () => {
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+            });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.upvotes).to.equal(15);
+            expect(state.downvotes).to.equal(6);
+        });
+
+        it("should call onDownvote hook", async () => {
+            const onDownvote = sinon.stub().resolves();
+            const state = createVoteState({ total: 10, onDownvote });
+            await state.ondownvoteclick();
+            expect(onDownvote).to.have.been.calledOnce;
+        });
+    });
+
+    describe("downvote - already downvoted (toggle off)", () => {
+        it("should increment total by 1", async () => {
+            const state = createVoteState({ total: 10, status: "downvoted" });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+        });
+
+        it("should set status to null", async () => {
+            const state = createVoteState({ total: 10, status: "downvoted" });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.status).to.equal(null);
+        });
+
+        it("should decrement downvotes when provided", async () => {
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                status: "downvoted",
+            });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.upvotes).to.equal(15);
+            expect(state.downvotes).to.equal(4);
+        });
+    });
+
+    describe("downvote - currently upvoted (switch)", () => {
+        it("should decrement total by 2", async () => {
+            const state = createVoteState({ total: 10, status: "upvoted" });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(8);
+        });
+
+        it("should set status to downvoted", async () => {
+            const state = createVoteState({ total: 10, status: "upvoted" });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.status).to.equal("downvoted");
+        });
+
+        it("should update upvotes and downvotes when provided", async () => {
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                status: "upvoted",
+            });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.upvotes).to.equal(14);
+            expect(state.downvotes).to.equal(6);
+        });
+    });
+
+    describe("error rollback", () => {
+        it("should rollback total on upvote error", async () => {
+            const onUpvote = sinon.stub().rejects(new Error("Server error"));
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(10);
+            expect(state.status).to.equal(null);
+        });
+
+        it("should rollback total on downvote error", async () => {
+            const onDownvote = sinon.stub().rejects(new Error("Server error"));
+            const state = createVoteState({ total: 10, onDownvote });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(10);
+            expect(state.status).to.equal(null);
+        });
+
+        it("should rollback all state on upvote error", async () => {
+            const onUpvote = sinon.stub().rejects(new Error("Server error"));
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                status: "downvoted",
+                onUpvote,
+            });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(10);
+            expect(state.upvotes).to.equal(15);
+            expect(state.downvotes).to.equal(5);
+            expect(state.status).to.equal("downvoted");
+        });
+
+        it("should rollback all state on downvote error", async () => {
+            const onDownvote = sinon.stub().rejects(new Error("Server error"));
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                status: "upvoted",
+                onDownvote,
+            });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(10);
+            expect(state.upvotes).to.equal(15);
+            expect(state.downvotes).to.equal(5);
+            expect(state.status).to.equal("upvoted");
+        });
+    });
+
+    describe("server response override", () => {
+        it("should override total with server value on upvote", async () => {
+            const onUpvote = sinon.stub().resolves({ total: 100 });
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(100);
+        });
+
+        it("should override total with server value on downvote", async () => {
+            const onDownvote = sinon.stub().resolves({ total: 50 });
+            const state = createVoteState({ total: 10, onDownvote });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(50);
+        });
+
+        it("should override all values with server response", async () => {
+            const onUpvote = sinon.stub().resolves({
+                total: 100,
+                upvotes: 120,
+                downvotes: 20,
+                status: "upvoted" as const,
+            });
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                onUpvote,
+            });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(100);
+            expect(state.upvotes).to.equal(120);
+            expect(state.downvotes).to.equal(20);
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should handle concurrent vote scenario (different total from server)", async () => {
+            // Simulate: user upvotes (optimistic: 11), but server says someone else
+            // also upvoted so actual total is 15
+            const onUpvote = sinon.stub().resolves({
+                total: 15,
+                upvotes: 20,
+                status: "upvoted" as const,
+            });
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                onUpvote,
+            });
+
+            // Before vote
+            expect(state.total).to.equal(10);
+
+            await state.onupvoteclick();
+            flushSync();
+
+            // Server returned different values due to concurrent votes
+            expect(state.total).to.equal(15);
+            expect(state.upvotes).to.equal(20);
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should partially override with server response", async () => {
+            // Server only returns total, not upvotes/downvotes
+            const onUpvote = sinon.stub().resolves({ total: 50 });
+            const state = createVoteState({
+                total: 10,
+                upvotes: 15,
+                downvotes: 5,
+                onUpvote,
+            });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(50);
+            // Optimistic update kept for upvotes
+            expect(state.upvotes).to.equal(16);
+            expect(state.downvotes).to.equal(5);
+        });
+
+        it("should keep optimistic update when hook returns void", async () => {
+            const onUpvote = sinon.stub().resolves();
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should keep optimistic update when hook returns undefined", async () => {
+            const onUpvote = sinon.stub().resolves(undefined);
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+        });
+    });
+
+    describe("programmatic setters", () => {
+        it("should allow setting total externally", () => {
+            const state = createVoteState({ total: 10 });
+            state.setTotal(50);
+            flushSync();
+            expect(state.total).to.equal(50);
+        });
+
+        it("should allow setting upvotes externally", () => {
+            const state = createVoteState({ total: 10, upvotes: 15 });
+            state.setUpvotes(25);
+            flushSync();
+            expect(state.upvotes).to.equal(25);
+        });
+
+        it("should allow setting downvotes externally", () => {
+            const state = createVoteState({ total: 10, downvotes: 5 });
+            state.setDownvotes(10);
+            flushSync();
+            expect(state.downvotes).to.equal(10);
+        });
+
+        it("should allow setting status externally", () => {
+            const state = createVoteState({ total: 10 });
+            state.setStatus("upvoted");
+            flushSync();
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should allow clearing upvotes", () => {
+            const state = createVoteState({ total: 10, upvotes: 15 });
+            state.setUpvotes(undefined);
+            flushSync();
+            expect(state.upvotes).to.be.undefined;
+        });
+    });
+
+    describe("without hooks", () => {
+        it("should work without onUpvote hook", async () => {
+            const state = createVoteState({ total: 10 });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should work without onDownvote hook", async () => {
+            const state = createVoteState({ total: 10 });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(9);
+            expect(state.status).to.equal("downvoted");
+        });
+    });
+
+    describe("synchronous hooks", () => {
+        it("should work with synchronous onUpvote hook", async () => {
+            const onUpvote = sinon.stub().returns({ total: 100 });
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(100);
+        });
+
+        it("should work with synchronous onDownvote hook", async () => {
+            const onDownvote = sinon.stub().returns({ total: 50 });
+            const state = createVoteState({ total: 10, onDownvote });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(50);
+        });
+
+        it("should rollback on synchronous error", async () => {
+            const onUpvote = sinon.stub().throws(new Error("Sync error"));
+            const state = createVoteState({ total: 10, onUpvote });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(10);
+            expect(state.status).to.equal(null);
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle negative totals", async () => {
+            const state = createVoteState({ total: 0 });
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(-1);
+        });
+
+        it("should handle zero total with upvote", async () => {
+            const state = createVoteState({ total: 0 });
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(1);
+        });
+
+        it("should handle multiple consecutive upvotes correctly", async () => {
+            const state = createVoteState({ total: 10 });
+
+            // First upvote
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+            expect(state.status).to.equal("upvoted");
+
+            // Second upvote (toggle off)
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(10);
+            expect(state.status).to.equal(null);
+
+            // Third upvote
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+            expect(state.status).to.equal("upvoted");
+        });
+
+        it("should handle upvote -> downvote -> upvote sequence", async () => {
+            const state = createVoteState({ total: 10 });
+
+            // Upvote
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+            expect(state.status).to.equal("upvoted");
+
+            // Downvote (switch)
+            await state.ondownvoteclick();
+            flushSync();
+            expect(state.total).to.equal(9);
+            expect(state.status).to.equal("downvoted");
+
+            // Upvote (switch back)
+            await state.onupvoteclick();
+            flushSync();
+            expect(state.total).to.equal(11);
+            expect(state.status).to.equal("upvoted");
+        });
+    });
+});
diff --git a/packages/stacks-svelte/src/components/Vote/vote-state.svelte.ts b/packages/stacks-svelte/src/components/Vote/vote-state.svelte.ts
new file mode 100644
index 0000000000..7810ffbbb9
--- /dev/null
+++ b/packages/stacks-svelte/src/components/Vote/vote-state.svelte.ts
@@ -0,0 +1,235 @@
+import type { Status } from "./Vote.svelte";
+
+/**
+ * Optional response from vote hooks containing server-authoritative values.
+ * When returned, these values override the optimistic update.
+ */
+export interface VoteServerResponse {
+    /**
+     * Server-authoritative total vote count
+     */
+    total?: number;
+
+    /**
+     * Server-authoritative upvotes count
+     */
+    upvotes?: number;
+
+    /**
+     * Server-authoritative downvotes count
+     */
+    downvotes?: number;
+
+    /**
+     * Server-authoritative vote status
+     */
+    status?: Status;
+}
+
+export interface VoteStateOptions {
+    /**
+     * Initial total vote count
+     */
+    total: number;
+
+    /**
+     * Initial upvotes count (optional, for expandable mode)
+     */
+    upvotes?: number;
+
+    /**
+     * Initial downvotes count (optional, for expandable mode)
+     */
+    downvotes?: number;
+
+    /**
+     * Initial vote status
+     */
+    status?: Status;
+
+    /**
+     * Hook called when user upvotes.
+     * - Return nothing to keep the optimistic update
+     * - Return VoteServerResponse to override with server values
+     * - Throw an error to rollback to previous state
+     */
+    onUpvote?: () =>
+        | Promise<VoteServerResponse | void>
+        | VoteServerResponse
+        | void;
+
+    /**
+     * Hook called when user downvotes.
+     * - Return nothing to keep the optimistic update
+     * - Return VoteServerResponse to override with server values
+     * - Throw an error to rollback to previous state
+     */
+    onDownvote?: () =>
+        | Promise<VoteServerResponse | void>
+        | VoteServerResponse
+        | void;
+}
+
+/**
+ * Creates a reactive vote state manager that can be spread to the Vote component.
+ *
+ * Features:
+ * - Automatic state management for total, upvotes, downvotes, and status
+ * - Optimistic updates with rollback on error
+ * - Server sync hooks (onUpvote, onDownvote) with optional server response handling
+ * - When hooks return VoteServerResponse, those values override the optimistic update
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import Vote from "./Vote.svelte";
+ *   import { createVoteState } from "./vote-state.svelte";
+ *
+ *   const voteState = createVoteState({
+ *     total: 12,
+ *     onUpvote: async () => {
+ *       const res = await fetch("/api/vote", {
+ *         method: "POST",
+ *         body: JSON.stringify({ vote: "up" })
+ *       });
+ *       const data = await res.json();
+ *       // Return server values to override optimistic update
+ *       return { total: data.total, upvotes: data.upvotes, downvotes: data.downvotes };
+ *     },
+ *     onDownvote: async () => {
+ *       const res = await fetch("/api/vote", {
+ *         method: "POST",
+ *         body: JSON.stringify({ vote: "down" })
+ *       });
+ *       const data = await res.json();
+ *       return { total: data.total };
+ *     },
+ *   });
+ * </script>
+ *
+ * <Vote {...voteState} />
+ * ```
+ */
+type VoteAction = "upvote" | "downvote";
+
+export function createVoteState(options: VoteStateOptions) {
+    let total = $state(options.total);
+    let upvotes = $state(options.upvotes);
+    let downvotes = $state(options.downvotes);
+    let status = $state<Status>(options.status ?? null);
+
+    /**
+     * Captures current state for potential rollback
+     */
+    const captureState = () => ({
+        total,
+        upvotes,
+        downvotes,
+        status,
+    });
+
+    /**
+     * Restores state from a captured snapshot
+     */
+    const restoreState = (snapshot: ReturnType<typeof captureState>) => {
+        total = snapshot.total;
+        upvotes = snapshot.upvotes;
+        downvotes = snapshot.downvotes;
+        status = snapshot.status;
+    };
+
+    /**
+     * Applies server response values, overriding optimistic updates
+     */
+    const applyServerResponse = (response: VoteServerResponse) => {
+        if (response.total !== undefined) total = response.total;
+        if (response.upvotes !== undefined) upvotes = response.upvotes;
+        if (response.downvotes !== undefined) downvotes = response.downvotes;
+        if (response.status !== undefined) status = response.status;
+    };
+
+    /**
+     * Applies optimistic update based on action and current status
+     */
+    const applyOptimisticUpdate = (action: VoteAction) => {
+        const isUpvote = action === "upvote";
+        const targetStatus: Status = isUpvote ? "upvoted" : "downvoted";
+        const oppositeStatus: Status = isUpvote ? "downvoted" : "upvoted";
+
+        if (status === targetStatus) {
+            // Toggle off current vote
+            total += isUpvote ? -1 : 1;
+            if (isUpvote && upvotes !== undefined) upvotes -= 1;
+            if (!isUpvote && downvotes !== undefined) downvotes -= 1;
+            status = null;
+        } else if (status === oppositeStatus) {
+            // Switch vote
+            total += isUpvote ? 2 : -2;
+            if (upvotes !== undefined) upvotes += isUpvote ? 1 : -1;
+            if (downvotes !== undefined) downvotes += isUpvote ? -1 : 1;
+            status = targetStatus;
+        } else {
+            // New vote
+            total += isUpvote ? 1 : -1;
+            if (isUpvote && upvotes !== undefined) upvotes += 1;
+            if (!isUpvote && downvotes !== undefined) downvotes += 1;
+            status = targetStatus;
+        }
+    };
+
+    /**
+     * Handles vote action with optimistic update, hook execution, and rollback on error
+     */
+    const handleVote = async (action: VoteAction) => {
+        const previousState = captureState();
+        const hook =
+            action === "upvote" ? options.onUpvote : options.onDownvote;
+
+        applyOptimisticUpdate(action);
+
+        if (hook) {
+            try {
+                const response = await hook();
+                if (response) {
+                    applyServerResponse(response);
+                }
+            } catch {
+                restoreState(previousState);
+            }
+        }
+    };
+
+    return {
+        // Getters for reactive state
+        get total() {
+            return total;
+        },
+        get upvotes() {
+            return upvotes;
+        },
+        get downvotes() {
+            return downvotes;
+        },
+        get status() {
+            return status;
+        },
+
+        // Click handlers for the Vote component
+        onupvoteclick: () => handleVote("upvote"),
+        ondownvoteclick: () => handleVote("downvote"),
+
+        // Programmatic setters for external updates
+        setTotal(value: number) {
+            total = value;
+        },
+        setUpvotes(value: number | undefined) {
+            upvotes = value;
+        },
+        setDownvotes(value: number | undefined) {
+            downvotes = value;
+        },
+        setStatus(value: Status) {
+            status = value;
+        },
+    };
+}

From 8bf84ba8423591f8e9f41e158b556e1a00b7f167 Mon Sep 17 00:00:00 2001
From: Giamir Buoncristiani <giamir.buoncristiani@gmail.com>
Date: Wed, 28 Jan 2026 16:58:10 +0100
Subject: [PATCH 2/5] add .svelte.ts files to eslint config

---
 packages/stacks-svelte/eslint.config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/stacks-svelte/eslint.config.js b/packages/stacks-svelte/eslint.config.js
index 395cc33e84..bfc8a1bcea 100644
--- a/packages/stacks-svelte/eslint.config.js
+++ b/packages/stacks-svelte/eslint.config.js
@@ -10,7 +10,7 @@ import pluginChaiFriendly from "eslint-plugin-chai-friendly";
 export default [
     eslint.configs.recommended,
     {
-        files: ["**/*.svelte", "*.svelte"],
+        files: ["**/*.svelte", "*.svelte", "**/*.svelte.ts", "*.svelte.ts"],
         languageOptions: {
             parser: svelteParser,
             parserOptions: {

From c6b965e748b598adaa78eeb7fbe5bc21b43bf808 Mon Sep 17 00:00:00 2001
From: Giamir Buoncristiani <giamir.buoncristiani@gmail.com>
Date: Wed, 28 Jan 2026 17:24:02 +0100
Subject: [PATCH 3/5] ensure vote component is exposed correctly

---
 .changeset/red-cobras-make.md                  | 5 +++++
 packages/stacks-svelte/src/components/index.ts | 2 ++
 2 files changed, 7 insertions(+)
 create mode 100644 .changeset/red-cobras-make.md

diff --git a/.changeset/red-cobras-make.md b/.changeset/red-cobras-make.md
new file mode 100644
index 0000000000..72d8b22c65
--- /dev/null
+++ b/.changeset/red-cobras-make.md
@@ -0,0 +1,5 @@
+---
+"@stackoverflow/stacks-svelte": patch
+---
+
+extract the vote state logic in an opt in svelte module
diff --git a/packages/stacks-svelte/src/components/index.ts b/packages/stacks-svelte/src/components/index.ts
index 68f9a47e50..1d097bcd9f 100644
--- a/packages/stacks-svelte/src/components/index.ts
+++ b/packages/stacks-svelte/src/components/index.ts
@@ -40,3 +40,5 @@ export { default as UserCard } from "./UserCard/UserCard.svelte";
 export { default as UserCardBadge } from "./UserCard/UserCardBadge.svelte";
 export { default as UserCardBling } from "./UserCard/UserCardBling.svelte";
 export { default as UserCardTime } from "./UserCard/UserCardTime.svelte";
+export { default as Vote } from "./Vote/Vote.svelte";
+export { createVoteState } from "./Vote/vote-state.svelte";

From e199873ee451a4fba64c01cd4c089c0e75cfaba1 Mon Sep 17 00:00:00 2001
From: Giamir Buoncristiani <giamir.buoncristiani@gmail.com>
Date: Wed, 28 Jan 2026 17:55:30 +0100
Subject: [PATCH 4/5] fix svelte unit testing configuration

---
 packages/stacks-svelte/.storybook/main.ts | 12 ------------
 packages/stacks-svelte/vite.config.ts     |  6 +++++-
 2 files changed, 5 insertions(+), 13 deletions(-)

diff --git a/packages/stacks-svelte/.storybook/main.ts b/packages/stacks-svelte/.storybook/main.ts
index 854e3c2203..26efd1aafa 100644
--- a/packages/stacks-svelte/.storybook/main.ts
+++ b/packages/stacks-svelte/.storybook/main.ts
@@ -22,17 +22,5 @@ const config: StorybookConfig = {
             },
         },
     },
-    viteFinal: (config) => {
-        // Include svelte-sonner in optimizeDeps to ensure its virtual CSS modules
-        // (from <style global> blocks) are properly processed by vite-plugin-svelte.
-        // Without this, Storybook fails to load the Toaster component styles.
-        // Note: svelte-sonner is excluded in vite.config.ts for test compatibility,
-        // but Storybook needs it included for proper CSS handling.
-        config!.optimizeDeps!.exclude = config?.optimizeDeps?.exclude?.filter(
-            (dep) => dep !== "svelte-sonner"
-        );
-
-        return config;
-    },
 };
 export default config;
diff --git a/packages/stacks-svelte/vite.config.ts b/packages/stacks-svelte/vite.config.ts
index e82ae64bad..d2ccb29d07 100644
--- a/packages/stacks-svelte/vite.config.ts
+++ b/packages/stacks-svelte/vite.config.ts
@@ -7,7 +7,6 @@ import path from "path";
 export default defineConfig({
     plugins: [svelte(svelteConfig), svelteTesting(), svelteInlineComponent()],
     optimizeDeps: {
-        exclude: ["svelte-sonner"],
         //without the following explicit includes, test runs fail on the first run because these dependencies don't get pre-optimized properly
         include: [
             "@web/test-runner-commands",
@@ -19,6 +18,11 @@ export default defineConfig({
             "@testing-library/user-event",
             "@stackoverflow/stacks-icons/icons",
             "@stackoverflow/stacks-icons-legacy/icons",
+            // svelte-sonner must be pre-bundled to ensure its virtual CSS modules
+            // (from <style global> blocks) are properly resolved during test execution.
+            // Without pre-bundling, CI environments may trigger mid-test re-optimization,
+            // causing "failed to load virtual css module" errors.
+            "svelte-sonner",
         ],
     },
     resolve: {

From de9b9d9721352cc203879852de71a718b3784470 Mon Sep 17 00:00:00 2001
From: Giamir Buoncristiani <giamir.buoncristiani@gmail.com>
Date: Wed, 28 Jan 2026 18:35:55 +0100
Subject: [PATCH 5/5] attempt to fix svelte unit tests

---
 packages/stacks-svelte/vite.config.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/stacks-svelte/vite.config.ts b/packages/stacks-svelte/vite.config.ts
index d2ccb29d07..b849fdcedb 100644
--- a/packages/stacks-svelte/vite.config.ts
+++ b/packages/stacks-svelte/vite.config.ts
@@ -17,7 +17,11 @@ export default defineConfig({
             "@testing-library/svelte",
             "@testing-library/user-event",
             "@stackoverflow/stacks-icons/icons",
+            "@stackoverflow/stacks-icons/spots",
             "@stackoverflow/stacks-icons-legacy/icons",
+            "dayjs",
+            "dayjs/plugin/relativeTime",
+            "dayjs/plugin/updateLocale",
             // svelte-sonner must be pre-bundled to ensure its virtual CSS modules
             // (from <style global> blocks) are properly resolved during test execution.
             // Without pre-bundling, CI environments may trigger mid-test re-optimization,