slidev-workspace 0.9.2 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidev-workspace",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "A workspace tool for managing multiple Slidev presentations with API-based content management",
   "type": "module",
   "license": "MIT",
@@ -52,20 +52,30 @@
     "yaml": "^2.8.0"
   },
   "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.0",
     "@prettier/plugin-oxc": "^0.0.4",
+    "@storybook/addon-a11y": "^10.2.3",
+    "@storybook/addon-docs": "^10.2.3",
+    "@storybook/addon-onboarding": "^10.2.3",
+    "@storybook/addon-vitest": "^10.2.3",
+    "@storybook/vue3-vite": "^10.2.3",
+    "@testing-library/vue": "^8.1.0",
     "@tsconfig/node22": "^22.0.2",
     "@types/node": "^22.15.32",
+    "@vitest/browser": "3.2.4",
     "@vue/tsconfig": "^0.7.0",
     "jiti": "^2.4.2",
     "npm-run-all2": "^8.0.4",
     "oxlint": "~1.1.0",
+    "playwright": "^1.58.1",
     "postcss": "^8.5.6",
     "prettier": "3.5.3",
+    "storybook": "^10.2.3",
     "tailwindcss": "^4.1.11",
     "tsdown": "^0.11.9",
     "typescript": "^5.8.3",
     "vite-plugin-vue-devtools": "^7.7.7",
-    "vitest": "^3.1.3",
+    "vitest": "3.2.4",
     "vue-tsc": "^3.0.3"
   },
   "scripts": {
@@ -75,6 +85,8 @@
     "test": "vitest",
     "typecheck": "vue-tsc --noEmit",
     "lint": "oxlint",
-    "format": "prettier --write src/"
+    "format": "prettier --write src/",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
   }
 }

package/src/preview/components/SlideCard.stories.ts

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+
+import "../assets/main.css";
+import SlideCard from "./SlideCard.vue";
+
+const meta: Meta<typeof SlideCard> = {
+  title: "Preview/SlideCard",
+  component: SlideCard,
+  args: {
+    title: "Design Systems 101",
+    description:
+      "Learn how to build scalable UI foundations with practical tokens, components, and patterns.",
+    url: "https://example.com",
+    author: "Lea Chiu",
+    date: "2026-02-01",
+    image: "https://picsum.photos/200",
+  },
+  render: (args) => ({
+    components: { SlideCard },
+    setup: () => ({ args }),
+    template: "<div class='max-w-sm'><SlideCard v-bind='args' /></div>",
+  }),
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SlideCard>;
+
+export const Default: Story = {};
+
+export const WithoutImage: Story = {
+  args: {
+    image: undefined,
+  },
+};
+
+export const LongText: Story = {
+  args: {
+    title:
+      "Building for the Next Billion Users: Design, Performance, and Accessibility, Accessibility",
+    description:
+      "A deep dive into performance budgets, resilient layouts, content strategies, and internationalization across diverse devices.",
+  },
+};

package/src/preview/components/SlideCard.vue

@@ -40,21 +40,6 @@
           description
         }}</CardDescription>
 
-        <div class="flex flex-wrap gap-1 mb-2">
-          <span
-            v-if="theme"
-            class="inline-flex items-center px-2 py-1 rounded-full text-xs bg-blue-100 text-blue-800"
-          >
-            {{ theme }}
-          </span>
-          <span
-            v-if="sourceDir"
-            class="inline-flex items-center px-2 py-1 rounded-full text-xs bg-green-100 text-green-800"
-          >
-            {{ sourceDir.split("/").pop() }}
-          </span>
-        </div>
-
         <div
           class="flex items-center justify-between text-xs text-muted-foreground pt-2 border-t"
         >
@@ -92,8 +77,6 @@ const props = defineProps<{
   url: string;
   author: string;
   date: string;
-  theme?: string;
-  sourceDir?: string;
 }>();
 
 defineEmits<{

package/src/preview/components/SlideDeck.vue

@@ -4,81 +4,16 @@
       <aside
         class="sw-sidebar w-full border-r border-border text-sidebar-foreground"
       >
-        <div
-          class="sticky top-0 flex h-screen flex-col px-6 py-10 text-sidebar-foreground w-[270px]"
-        >
-          <div class="px-1 pb-4">
-            <h2 class="text-lg font-semibold tracking-tight">
-              {{ sidebar.title }}
-            </h2>
-          </div>
-
-          <div class="px-1 pb-6">
-            <div class="relative w-full">
-              <Input
-                class="pl-10 h-10 rounded-xl bg-background/70"
-                placeholder="Search slides..."
-                v-model="searchTerm"
-              />
-              <span
-                class="absolute start-0 inset-y-0 flex items-center justify-center px-3"
-              >
-                <Search class="size-5 text-muted-foreground/50" />
-              </span>
-            </div>
-          </div>
-
-          <div class="px-1 pb-2">
-            <h3
-              class="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
-            >
-              Categories
-            </h3>
-          </div>
-
-          <div class="px-0.5 space-y-1 max-h-[60vh] overflow-auto">
-            <button
-              v-for="category in categoryOptions"
-              :key="category.name"
-              type="button"
-              @click="selectedCategory = category.name"
-              class="w-full flex items-center justify-between rounded-xl px-3 py-2 text-left text-sm transition-colors"
-              :class="
-                selectedCategory === category.name
-                  ? 'bg-sidebar-accent text-sidebar-accent-foreground'
-                  : 'hover:bg-sidebar-accent/70 text-sidebar-foreground'
-              "
-            >
-              <span class="truncate">{{ category.name }}</span>
-              <span class="text-xs text-muted-foreground">{{
-                category.count
-              }}</span>
-            </button>
-          </div>
-
-          <div class="mt-auto flex items-center justify-between gap-3 pt-6">
-            <a
-              v-if="sidebar.githubUrl"
-              :href="sidebar.githubUrl"
-              target="_blank"
-              rel="noreferrer"
-              class="inline-flex items-center justify-center rounded-lg p-2 text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors cursor-pointer"
-              aria-label="Open GitHub repository"
-            >
-              <Github class="size-5" />
-            </a>
-            <div v-else />
-            <button
-              @click="toggleDarkMode"
-              class="p-2 rounded-lg hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors cursor-pointer"
-              aria-label="Toggle dark mode"
-              type="button"
-            >
-              <Moon v-if="!isDark" class="size-5" />
-              <Sun v-else class="size-5" />
-            </button>
-          </div>
-        </div>
+        <SlideSidebar
+          :title="sidebar.title"
+          :github-url="sidebar.githubUrl"
+          :categories="categoryOptions"
+          :is-dark="isDark"
+          variant="desktop"
+          v-model:search-term="searchTerm"
+          v-model:selected-category="selectedCategory"
+          @toggle-dark="toggleDarkMode"
+        />
       </aside>
 
       <header class="sw-header">
@@ -95,83 +30,16 @@
                 </button>
               </DrawerTrigger>
               <DrawerContent class="sw-drawer text-sidebar-foreground">
-                <div
-                  class="flex h-full flex-col px-6 py-8 text-sidebar-foreground"
-                >
-                  <div class="px-1 pb-4">
-                    <h2 class="text-lg font-semibold tracking-tight">
-                      {{ sidebar.title }}
-                    </h2>
-                  </div>
-
-                  <div class="px-1 pb-6">
-                    <div class="relative w-full">
-                      <Input
-                        class="pl-10 h-10 rounded-xl bg-background/70"
-                        placeholder="Search slides..."
-                        v-model="searchTerm"
-                      />
-                      <span
-                        class="absolute start-0 inset-y-0 flex items-center justify-center px-3"
-                      >
-                        <Search class="size-5 text-muted-foreground/50" />
-                      </span>
-                    </div>
-                  </div>
-
-                  <div class="px-1 pb-2">
-                    <h3
-                      class="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
-                    >
-                      Categories
-                    </h3>
-                  </div>
-
-                  <div class="px-0.5 space-y-1 flex-1 overflow-auto">
-                    <button
-                      v-for="category in categoryOptions"
-                      :key="category.name"
-                      type="button"
-                      @click="selectedCategory = category.name"
-                      class="w-full flex items-center justify-between rounded-xl px-3 py-2 text-left text-sm transition-colors"
-                      :class="
-                        selectedCategory === category.name
-                          ? 'bg-sidebar-accent text-sidebar-accent-foreground'
-                          : 'hover:bg-sidebar-accent/70 text-sidebar-foreground'
-                      "
-                    >
-                      <span class="truncate">{{ category.name }}</span>
-                      <span class="text-xs text-muted-foreground">{{
-                        category.count
-                      }}</span>
-                    </button>
-                  </div>
-
-                  <div
-                    class="mt-auto flex items-center justify-between gap-3 pt-6"
-                  >
-                    <a
-                      v-if="sidebar.githubUrl"
-                      :href="sidebar.githubUrl"
-                      target="_blank"
-                      rel="noreferrer"
-                      class="inline-flex items-center justify-center rounded-lg p-2 text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors cursor-pointer"
-                      aria-label="Open GitHub repository"
-                    >
-                      <Github class="size-5" />
-                    </a>
-                    <div v-else />
-                    <button
-                      @click="toggleDarkMode"
-                      class="p-2 rounded-lg hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors cursor-pointer"
-                      aria-label="Toggle dark mode"
-                      type="button"
-                    >
-                      <Moon v-if="!isDark" class="size-5" />
-                      <Sun v-else class="size-5" />
-                    </button>
-                  </div>
-                </div>
+                <SlideSidebar
+                  :title="sidebar.title"
+                  :github-url="sidebar.githubUrl"
+                  :categories="categoryOptions"
+                  :is-dark="isDark"
+                  variant="drawer"
+                  v-model:search-term="searchTerm"
+                  v-model:selected-category="selectedCategory"
+                  @toggle-dark="toggleDarkMode"
+                />
               </DrawerContent>
             </Drawer>
 
@@ -230,14 +98,14 @@
 
 <script setup lang="ts">
 import { ref, computed, watch } from "vue";
-import { Search, Moon, Sun, Github, PanelLeft } from "lucide-vue-next";
+import { PanelLeft } from "lucide-vue-next";
 
 import { useSlides } from "../composables/useSlides";
 import { useConfig } from "../composables/useConfig";
 import { useDarkMode } from "../composables/useDarkMode";
-import { Input } from "../components/ui/input";
 import { Drawer, DrawerContent, DrawerTrigger } from "../components/ui/drawer";
 import SlideCard from "./SlideCard.vue";
+import SlideSidebar from "./SlideSidebar.vue";
 
 const searchTerm = ref("");
 const { slides, slidesCount } = useSlides();

package/src/preview/components/SlideSidebar.stories.ts

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+
+import "../assets/main.css";
+import SlideSidebar from "./SlideSidebar.vue";
+
+const meta: Meta<typeof SlideSidebar> = {
+  title: "Preview/SlideSidebar",
+  component: SlideSidebar,
+  args: {
+    title: "Slide Deck",
+    githubUrl: "https://github.com/slidevjs/slidev",
+    categories: [
+      {
+        name: "All",
+      },
+      {
+        name: "tech-slides",
+      },
+      {
+        name: "tech",
+        categories: [
+          {
+            name: "slides",
+          },
+          {
+            name: "workshops",
+            categories: [
+              {
+                name: "frontend",
+              },
+              {
+                name: "backend",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        name: "design",
+        categories: [
+          {
+            name: "systems",
+          },
+        ],
+      },
+    ],
+    selectedCategory: "tech/slides",
+    searchTerm: "",
+    isDark: false,
+    variant: "desktop",
+  },
+  argTypes: {
+    variant: {
+      control: "inline-radio",
+      options: ["desktop", "drawer"],
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SlideSidebar>;
+
+export const Desktop: Story = {};
+
+export const Drawer: Story = {
+  args: {
+    variant: "drawer",
+  },
+};

package/src/preview/components/SlideSidebar.vue

@@ -0,0 +1,143 @@
+<template>
+  <div :class="containerClass">
+    <div class="px-1 pb-4">
+      <h2 class="text-lg font-semibold tracking-tight">
+        {{ title }}
+      </h2>
+    </div>
+
+    <div class="px-1 pb-6">
+      <div class="relative w-full">
+        <Input
+          class="pl-10 h-10 rounded-xl bg-background/70"
+          placeholder="Search slides..."
+          v-model="searchTerm"
+        />
+        <span
+          class="absolute start-0 inset-y-0 flex items-center justify-center px-3"
+        >
+          <Search class="size-5 text-muted-foreground/50" />
+        </span>
+      </div>
+    </div>
+
+    <div class="px-1 pb-2">
+      <h3
+        class="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
+      >
+        Categories
+      </h3>
+    </div>
+
+    <div :class="categoriesClass">
+      <button
+        v-if="allCategory"
+        :key="allCategory.name"
+        type="button"
+        @click="selectedCategory = allCategory.name"
+        class="mb-2 w-full flex items-center justify-between rounded-xl px-3 py-2 text-left text-sm transition-colors"
+        :class="
+          selectedCategory === allCategory.name
+            ? 'bg-sidebar-accent text-sidebar-accent-foreground ring-1 ring-sidebar-border/70 dark:ring-sidebar-border/30'
+            : 'hover:bg-sidebar-accent/70 text-sidebar-foreground'
+        "
+      >
+        <span class="truncate">{{ allCategory.name }}</span>
+      </button>
+
+      <div
+        v-if="categoryTree.length === 0 && !allCategory"
+        class="px-3 py-2 text-xs text-muted-foreground"
+      >
+        No categories yet.
+      </div>
+
+      <TreeView
+        v-else
+        :nodes="categoryTree"
+        v-model:selected="selectedCategory"
+      />
+    </div>
+
+    <div class="mt-auto flex items-center justify-between gap-3 pt-6">
+      <a
+        v-if="githubUrl"
+        :href="githubUrl"
+        target="_blank"
+        rel="noreferrer"
+        class="inline-flex items-center justify-center rounded-lg p-2 text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors cursor-pointer"
+        aria-label="Open GitHub repository"
+      >
+        <Github class="size-5" />
+      </a>
+      <div v-else />
+      <button
+        @click="emit('toggle-dark', $event)"
+        class="p-2 rounded-lg hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors cursor-pointer"
+        aria-label="Toggle dark mode"
+        type="button"
+      >
+        <Moon v-if="!isDark" class="size-5" />
+        <Sun v-else class="size-5" />
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import { Github, Moon, Search, Sun } from "lucide-vue-next";
+
+import { Input } from "../components/ui/input";
+import {
+  normalizeCategories,
+  type CategoryNodeInput,
+} from "../lib/categoryTree";
+import TreeView from "./TreeView.vue";
+
+const props = withDefaults(
+  defineProps<{
+    title: string;
+    githubUrl?: string;
+    categories: CategoryNodeInput[];
+    isDark: boolean;
+    variant?: "desktop" | "drawer";
+  }>(),
+  {
+    variant: "desktop",
+  },
+);
+
+const emit = defineEmits<{
+  (e: "toggle-dark", event: MouseEvent): void;
+}>();
+
+const searchTerm = defineModel<string>("searchTerm", { default: "" });
+const selectedCategory = defineModel<string>("selectedCategory", {
+  default: "All",
+});
+
+const ALL_CATEGORY_LABEL = "All";
+
+const allCategory = computed(() =>
+  props.categories.find((category) => category.name === ALL_CATEGORY_LABEL),
+);
+
+const containerClass = computed(() =>
+  props.variant === "drawer"
+    ? "flex h-full flex-col px-6 py-8 text-sidebar-foreground"
+    : "sticky top-0 flex h-screen w-[270px] flex-col px-6 py-10 text-sidebar-foreground",
+);
+
+const categoriesClass = computed(() =>
+  props.variant === "drawer"
+    ? "px-0.5 pb-2 space-y-1 flex-1 overflow-auto"
+    : "px-0.5 pb-2 space-y-1 max-h-[60vh] overflow-auto",
+);
+
+const categoryTree = computed(() =>
+  normalizeCategories(
+    props.categories.filter((category) => category.name !== ALL_CATEGORY_LABEL),
+  ),
+);
+</script>

package/src/preview/components/TreeView.stories.ts

@@ -0,0 +1,84 @@
+import { ref } from "vue";
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+
+import "../assets/main.css";
+import TreeView from "./TreeView.vue";
+import type { TreeNode } from "../lib/categoryTree";
+
+const sampleNodes: TreeNode[] = [
+  {
+    name: "tech-slides",
+    path: "tech-slides",
+    children: [],
+  },
+  {
+    name: "tech",
+    path: "tech",
+    children: [
+      {
+        name: "slides",
+        path: "tech/slides",
+        children: [],
+      },
+      {
+        name: "workshops",
+        path: "tech/workshops",
+        children: [],
+      },
+    ],
+  },
+  {
+    name: "design",
+    path: "design",
+    children: [
+      {
+        name: "systems",
+        path: "design/systems",
+        children: [],
+      },
+    ],
+  },
+];
+
+type TreeViewStoryArgs = {
+  nodes: TreeNode[];
+  selected: string;
+  expandedPaths: string[];
+};
+
+const meta: Meta<TreeViewStoryArgs> = {
+  title: "Preview/TreeView",
+  component: TreeView,
+};
+
+export default meta;
+
+type Story = StoryObj<TreeViewStoryArgs>;
+
+export const Default: Story = {
+  args: {
+    nodes: sampleNodes,
+    selected: "tech/slides",
+    expandedPaths: ["tech"],
+  },
+  argTypes: {
+    expandedPaths: {
+      control: "object",
+    },
+  },
+  render: (args: TreeViewStoryArgs) => ({
+    components: { TreeView },
+    setup() {
+      const selected = ref(args.selected);
+      const expanded = ref(new Set(args.expandedPaths));
+
+      return {
+        args,
+        selected,
+        expanded,
+      };
+    },
+    template:
+      '<TreeView :nodes="args.nodes" v-model:selected="selected" v-model:expanded="expanded" />',
+  }),
+};

package/src/preview/components/TreeView.test.ts

@@ -0,0 +1,84 @@
+import { fireEvent, render, screen } from "@testing-library/vue";
+import { describe, expect, it, vi } from "vitest";
+
+import TreeView from "./TreeView.vue";
+import type { TreeNode } from "../lib/categoryTree";
+
+const sampleNodes: TreeNode[] = [
+  {
+    name: "tech-slides",
+    path: "tech-slides",
+    children: [],
+  },
+  {
+    name: "tech",
+    path: "tech",
+    children: [
+      {
+        name: "slides",
+        path: "tech/slides",
+        children: [],
+      },
+      {
+        name: "workshops",
+        path: "tech/workshops",
+        children: [],
+      },
+    ],
+  },
+  {
+    name: "design",
+    path: "design",
+    children: [
+      {
+        name: "systems",
+        path: "design/systems",
+        children: [],
+      },
+    ],
+  },
+];
+
+describe("TreeView", () => {
+  it("emits expanded updates for parent nodes", async () => {
+    const onUpdateExpanded = vi.fn();
+
+    render(TreeView, {
+      props: {
+        nodes: sampleNodes,
+        selected: "",
+        expanded: new Set<string>(),
+        "onUpdate:selected": vi.fn(),
+        "onUpdate:expanded": onUpdateExpanded,
+      },
+    });
+
+    const techButton = screen.getByRole("button", { name: "tech" });
+    expect(techButton.getAttribute("aria-expanded")).toBe("false");
+
+    await fireEvent.click(techButton);
+
+    expect(onUpdateExpanded).toHaveBeenCalledTimes(1);
+    const nextExpanded = onUpdateExpanded.mock.calls[0][0] as Set<string>;
+    expect(nextExpanded.has("tech")).toBe(true);
+  });
+
+  it("emits selection updates for leaf nodes", async () => {
+    const onUpdateSelected = vi.fn();
+
+    render(TreeView, {
+      props: {
+        nodes: sampleNodes,
+        selected: "",
+        expanded: new Set<string>(["tech"]),
+        "onUpdate:selected": onUpdateSelected,
+        "onUpdate:expanded": vi.fn(),
+      },
+    });
+
+    const slidesButton = screen.getByRole("button", { name: "slides" });
+    await fireEvent.click(slidesButton);
+
+    expect(onUpdateSelected).toHaveBeenCalledWith("tech/slides");
+  });
+});

package/src/preview/components/TreeView.vue

@@ -0,0 +1,92 @@
+<template>
+  <div class="space-y-2">
+    <div v-for="node in nodes" :key="node.path" class="space-y-1">
+      <button
+        type="button"
+        class="w-full flex items-center justify-between rounded-xl text-left transition-colors"
+        :class="rowClass(node, 1)"
+        :aria-expanded="node.children.length > 0 ? isExpanded(node) : undefined"
+        @click="handleNodeClick(node, 1)"
+      >
+        <span class="truncate">{{ node.name }}</span>
+        <ChevronRight
+          v-if="node.children.length > 0"
+          class="size-4 text-muted-foreground transition-transform"
+          :class="isExpanded(node) ? 'rotate-90' : ''"
+        />
+      </button>
+
+      <div v-if="isExpanded(node)" class="space-y-1 pl-3">
+        <div v-for="child in node.children" :key="child.path" class="space-y-1">
+          <button
+            type="button"
+            class="w-full flex items-center justify-between rounded-lg text-left transition-colors"
+            :class="rowClass(child, 2)"
+            @click="handleNodeClick(child, 2)"
+          >
+            <span class="truncate">{{ child.name }}</span>
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ChevronRight } from "lucide-vue-next";
+
+import type { TreeNode } from "../lib/categoryTree";
+
+defineProps<{
+  nodes: TreeNode[];
+}>();
+
+const selected = defineModel<string>("selected", { default: "" });
+const expanded = defineModel<Set<string>>("expanded", {
+  default: () => new Set<string>(),
+});
+
+const isExpanded = (node: TreeNode) => expanded.value.has(node.path);
+
+const isSelected = (node: TreeNode) => selected.value === node.path;
+
+const isAncestorSelected = (node: TreeNode) => {
+  if (!selected.value) return false;
+  return selected.value.startsWith(`${node.path}/`);
+};
+
+// The current TreeView UI only supports two nesting levels.
+// Deeper trees should be flattened or handled by a future recursive version.
+const rowClass = (node: TreeNode, level: 1 | 2) => {
+  const size = level === 1 ? "px-3 py-2 text-sm" : "px-3 py-1.5 text-sm";
+
+  if (isSelected(node)) {
+    return `${size} bg-sidebar-accent text-sidebar-accent-foreground ring-1 ring-sidebar-border/70 dark:ring-sidebar-border/30`;
+  }
+
+  if (isAncestorSelected(node)) {
+    return `${size} bg-sidebar-accent/40 text-sidebar-foreground`;
+  }
+
+  return `${size} hover:bg-sidebar-accent/70 text-sidebar-foreground`;
+};
+
+const toggleExpanded = (node: TreeNode) => {
+  const next = new Set(expanded.value);
+  if (next.has(node.path)) {
+    next.delete(node.path);
+  } else {
+    next.add(node.path);
+  }
+  expanded.value = next;
+};
+
+const handleNodeClick = (node: TreeNode, level: 1 | 2) => {
+  if (level === 1 && node.children.length > 0) {
+    toggleExpanded(node);
+    return;
+  }
+
+  selected.value = node.path;
+};
+</script>

package/src/preview/lib/categoryTree.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+
+import { normalizeCategories, type CategoryNodeInput } from "./categoryTree";
+
+describe("normalizeCategories", () => {
+  it("returns an empty array when no categories are provided", () => {
+    expect(normalizeCategories([])).toEqual([]);
+  });
+
+  it("builds a tree from flat category paths and sorts nodes", () => {
+    const input: CategoryNodeInput[] = [
+      { name: "tech/workshops" },
+      { name: "design/systems" },
+      { name: "tech/slides" },
+    ];
+
+    expect(normalizeCategories(input)).toEqual([
+      {
+        name: "design",
+        path: "design",
+        children: [
+          {
+            name: "systems",
+            path: "design/systems",
+            children: [],
+          },
+        ],
+      },
+      {
+        name: "tech",
+        path: "tech",
+        children: [
+          {
+            name: "slides",
+            path: "tech/slides",
+            children: [],
+          },
+          {
+            name: "workshops",
+            path: "tech/workshops",
+            children: [],
+          },
+        ],
+      },
+    ]);
+  });
+
+  it("prefers nested shape when provided and respects explicit paths", () => {
+    const input: CategoryNodeInput[] = [
+      {
+        name: "tech",
+        categories: [{ name: "workshops" }, { name: "slides" }],
+      },
+      {
+        name: "design",
+      },
+      {
+        name: "special",
+        path: "custom",
+        categories: [{ name: "vip" }],
+      },
+    ];
+
+    expect(normalizeCategories(input)).toEqual([
+      {
+        name: "design",
+        path: "design",
+        children: [],
+      },
+      {
+        name: "special",
+        path: "custom",
+        children: [
+          {
+            name: "vip",
+            path: "custom/vip",
+            children: [],
+          },
+        ],
+      },
+      {
+        name: "tech",
+        path: "tech",
+        children: [
+          {
+            name: "slides",
+            path: "tech/slides",
+            children: [],
+          },
+          {
+            name: "workshops",
+            path: "tech/workshops",
+            children: [],
+          },
+        ],
+      },
+    ]);
+  });
+});

package/src/preview/lib/categoryTree.ts

@@ -0,0 +1,99 @@
+export interface CategoryNodeInput {
+  name: string;
+  categories?: CategoryNodeInput[];
+  count?: number;
+  path?: string;
+}
+
+export interface TreeNode {
+  name: string;
+  path: string;
+  children: TreeNode[];
+}
+
+type RawNode = {
+  name: string;
+  path: string;
+  children: RawNode[];
+};
+
+export function normalizeCategories(
+  categories: CategoryNodeInput[],
+): TreeNode[] {
+  if (categories.length === 0) return [];
+  const hasTreeShape = categories.some(
+    (category) => category.categories && category.categories.length > 0,
+  );
+
+  const rawNodes = sortRawNodes(
+    hasTreeShape
+      ? buildTreeFromNested(categories)
+      : buildTreeFromFlat(categories),
+  );
+
+  return finalizeNodes(rawNodes);
+}
+
+function buildTreeFromNested(
+  categories: CategoryNodeInput[],
+  parentPath = "",
+): RawNode[] {
+  return categories
+    .map((category) => {
+      const path =
+        category.path ??
+        (parentPath ? `${parentPath}/${category.name}` : category.name);
+      return {
+        name: category.name,
+        path,
+        children: buildTreeFromNested(category.categories ?? [], path),
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function buildTreeFromFlat(categories: CategoryNodeInput[]): RawNode[] {
+  const root: RawNode[] = [];
+
+  for (const category of categories) {
+    const categoryPath = category.path ?? category.name;
+    const segments = categoryPath.split("/").filter(Boolean);
+    let current = root;
+    let currentPath = "";
+
+    for (const segment of segments) {
+      const nextPath = currentPath ? `${currentPath}/${segment}` : segment;
+      let node = current.find((candidate) => candidate.path === nextPath);
+      if (!node) {
+        node = {
+          name: segment,
+          path: nextPath,
+          children: [],
+        };
+        current.push(node);
+      }
+      current = node.children;
+      currentPath = nextPath;
+    }
+  }
+
+  return root.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function finalizeNodes(nodes: RawNode[]): TreeNode[] {
+  return nodes.map((node) => ({
+    name: node.name,
+    path: node.path,
+    children: finalizeNodes(node.children),
+  }));
+}
+
+function sortRawNodes(nodes: RawNode[]): RawNode[] {
+  return nodes
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((node) => ({
+      ...node,
+      children: sortRawNodes(node.children),
+    }));
+}