@aleph-alpha/ui-library 1.13.0 → 1.15.0

package/src/components/UiSidebar/UiSidebar.stories.ts

@@ -0,0 +1,1188 @@
+import { ref, computed, defineComponent } from 'vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarFooter,
+  UiSidebarGroup,
+  UiSidebarGroupAction,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarHeader,
+  UiSidebarHeaderTrigger,
+  UiSidebarInput,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuAction,
+  UiSidebarMenuBadge,
+  UiSidebarMenuButton,
+  UiSidebarMenuItem,
+  UiSidebarMenuSkeleton,
+  UiSidebarMenuSub,
+  UiSidebarMenuSubButton,
+  UiSidebarMenuSubItem,
+  UiSidebarProvider,
+  UiSidebarRail,
+  UiSidebarSeparator,
+  UiSidebarTrigger,
+  useSidebar,
+} from '.';
+import { CollapsibleRoot, CollapsibleContent, CollapsibleTrigger } from 'reka-ui';
+import {
+  Bot,
+  Database,
+  BarChart3,
+  MessageSquare,
+  Settings,
+  Command,
+  Plus,
+  MoreHorizontal,
+  FlaskConical,
+  Key,
+  Activity,
+  ChevronRight,
+} from 'lucide-vue-next';
+
+const meta: Meta<typeof UiSidebar> = {
+  title: 'Components/UiSidebar',
+  component: UiSidebar,
+  tags: ['autodocs'],
+  argTypes: {
+    side: {
+      control: 'select',
+      options: ['left', 'right'],
+    },
+    variant: {
+      control: 'select',
+      options: ['sidebar', 'floating', 'inset'],
+      description:
+        '`sidebar`: fixed with border. `floating`: shadow and rounded corners. `inset`: shares background with content.',
+    },
+    collapsible: {
+      control: 'select',
+      options: ['offcanvas', 'icon', 'none'],
+      description:
+        '`offcanvas`: slides completely off screen. `icon`: collapses to icon-only width. `none`: always expanded.',
+    },
+  },
+  args: {
+    side: 'left',
+    variant: 'sidebar',
+    collapsible: 'icon',
+  },
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    () => ({
+      template: '<div class="-m-4"><story /></div>',
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof UiSidebar>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarFooter,
+  UiSidebarGroup,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarHeaderTrigger,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuBadge,
+  UiSidebarMenuButton,
+  UiSidebarMenuItem,
+  UiSidebarProvider,
+  UiSidebarRail,
+} from '@aleph-alpha/ui-library'
+import { Bot, Database, BarChart3, MessageSquare, Settings, Command } from 'lucide-vue-next'
+
+const items = [
+  { title: 'Playground', url: '#', icon: Bot, badge: null },
+  { title: 'Models', url: '#', icon: Database, badge: '5' },
+  { title: 'Evaluations', url: '#', icon: BarChart3, badge: '3' },
+  { title: 'Conversations', url: '#', icon: MessageSquare, badge: null },
+]
+</script>
+
+<template>
+  <UiSidebarProvider :default-open="false">
+    <UiSidebar>
+      <UiSidebarHeaderTrigger>
+        <template #logo>
+          <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+            <Command class="size-4" />
+          </div>
+        </template>
+        <span class="truncate font-semibold">Acme AI</span>
+        <span class="truncate text-xs">Enterprise</span>
+      </UiSidebarHeaderTrigger>
+      <UiSidebarContent>
+        <UiSidebarGroup>
+          <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+          <UiSidebarGroupContent>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem v-for="item in items" :key="item.title">
+                <UiSidebarMenuButton :tooltip="item.title">
+                  <component :is="item.icon" />
+                  <span>{{ item.title }}</span>
+                </UiSidebarMenuButton>
+                <UiSidebarMenuBadge v-if="item.badge">
+                  {{ item.badge }}
+                </UiSidebarMenuBadge>
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+          </UiSidebarGroupContent>
+        </UiSidebarGroup>
+      </UiSidebarContent>
+      <UiSidebarFooter>
+        <UiSidebarMenu>
+          <UiSidebarMenuItem>
+            <UiSidebarMenuButton>
+              <Settings />
+              <span>Settings</span>
+            </UiSidebarMenuButton>
+          </UiSidebarMenuItem>
+        </UiSidebarMenu>
+      </UiSidebarFooter>
+      <UiSidebarRail />
+    </UiSidebar>
+    <UiSidebarInset>
+      <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+        <div class="flex items-center gap-1.5 text-sm">
+          <span class="text-muted-foreground">Platform</span>
+          <span class="text-muted-foreground">/</span>
+          <span class="font-medium">Playground</span>
+        </div>
+      </header>
+      <div class="flex flex-1 flex-col gap-4 p-4">
+        <div class="grid auto-rows-min gap-4 md:grid-cols-3">
+          <div class="aspect-video rounded-xl bg-muted" />
+          <div class="aspect-video rounded-xl bg-muted" />
+          <div class="aspect-video rounded-xl bg-muted" />
+        </div>
+        <div class="min-h-[50vh] flex-1 rounded-xl bg-muted" />
+      </div>
+    </UiSidebarInset>
+  </UiSidebarProvider>
+</template>`;
+
+/**
+ * AI platform sidebar with a company header, icon-based navigation group with `UiSidebarMenuBadge` counters, footer, and inset content area with breadcrumb header.
+ * Uses `collapsible="icon"` — the sidebar collapses to a narrow icon-only rail. Menu items show only their icon with a tooltip on hover. Badges auto-hide in collapsed mode.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: {
+      UiSidebar,
+      UiSidebarContent,
+      UiSidebarFooter,
+      UiSidebarGroup,
+      UiSidebarGroupContent,
+      UiSidebarGroupLabel,
+      UiSidebarHeaderTrigger,
+      UiSidebarInset,
+      UiSidebarMenu,
+      UiSidebarMenuBadge,
+      UiSidebarMenuButton,
+      UiSidebarMenuItem,
+      UiSidebarProvider,
+      UiSidebarRail,
+      Bot,
+      Database,
+      BarChart3,
+      MessageSquare,
+      Settings,
+      Command,
+    },
+    setup() {
+      const items = [
+        { title: 'Playground', url: '#', icon: Bot, badge: null },
+        { title: 'Models', url: '#', icon: Database, badge: '5' },
+        { title: 'Evaluations', url: '#', icon: BarChart3, badge: '3' },
+        { title: 'Conversations', url: '#', icon: MessageSquare, badge: null },
+      ];
+      return { args, items };
+    },
+    template: `
+      <UiSidebarProvider :default-open="false">
+        <UiSidebar :side="args.side" :variant="args.variant" :collapsible="args.collapsible">
+          <UiSidebarHeaderTrigger>
+            <template #logo>
+              <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                <Command class="size-4" />
+              </div>
+            </template>
+            <span class="truncate font-semibold">Acme AI</span>
+            <span class="truncate text-xs">Enterprise</span>
+          </UiSidebarHeaderTrigger>
+          <UiSidebarContent>
+            <UiSidebarGroup>
+              <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <UiSidebarMenuItem v-for="item in items" :key="item.title">
+                    <UiSidebarMenuButton :tooltip="item.title">
+                      <component :is="item.icon" />
+                      <span>{{ item.title }}</span>
+                    </UiSidebarMenuButton>
+                    <UiSidebarMenuBadge v-if="item.badge">
+                      {{ item.badge }}
+                    </UiSidebarMenuBadge>
+                  </UiSidebarMenuItem>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+          </UiSidebarContent>
+          <UiSidebarFooter>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem>
+                <UiSidebarMenuButton>
+                  <Settings />
+                  <span>Settings</span>
+                </UiSidebarMenuButton>
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+          </UiSidebarFooter>
+          <UiSidebarRail />
+        </UiSidebar>
+        <UiSidebarInset>
+          <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+            <div class="flex items-center gap-1.5 text-sm">
+              <span class="text-muted-foreground">Platform</span>
+              <span class="text-muted-foreground">/</span>
+              <span class="font-medium">Playground</span>
+            </div>
+          </header>
+          <div class="flex flex-1 flex-col gap-4 p-4">
+            <div class="grid auto-rows-min gap-4 md:grid-cols-3">
+              <div class="aspect-video rounded-xl bg-muted" />
+              <div class="aspect-video rounded-xl bg-muted" />
+              <div class="aspect-video rounded-xl bg-muted" />
+            </div>
+            <div class="min-h-[50vh] flex-1 rounded-xl bg-muted" />
+          </div>
+        </UiSidebarInset>
+      </UiSidebarProvider>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const withSearchTemplateSource = `<script setup lang="ts">
+import { ref, computed } from 'vue'
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarGroup,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarHeader,
+  UiSidebarInput,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuButton,
+  UiSidebarMenuItem,
+  UiSidebarProvider,
+  UiSidebarTrigger,
+} from '@aleph-alpha/ui-library'
+import { Command } from 'lucide-vue-next'
+
+const groups = [
+  {
+    label: 'Getting Started',
+    items: ['Quick Start', 'Authentication', 'API Keys'],
+  },
+  {
+    label: 'Models',
+    items: ['Completions', 'Embeddings', 'Chat', 'Multimodal'],
+  },
+  {
+    label: 'Advanced',
+    items: ['Fine-tuning', 'Prompt Engineering', 'Evaluation', 'RAG'],
+  },
+]
+
+const query = ref('')
+const filteredGroups = computed(() =>
+  groups
+    .map(group => ({
+      ...group,
+      items: group.items.filter(item =>
+        item.toLowerCase().includes(query.value.toLowerCase())
+      ),
+    }))
+    .filter(group => group.items.length > 0)
+)
+</script>
+
+<template>
+  <UiSidebarProvider :default-open="true">
+    <UiSidebar>
+      <UiSidebarHeader>
+        <UiSidebarMenu>
+          <UiSidebarMenuItem>
+            <UiSidebarMenuButton size="lg">
+              <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                <Command class="size-4" />
+              </div>
+              <div class="grid flex-1 text-left text-sm leading-tight">
+                <span class="truncate font-semibold">API Docs</span>
+                <span class="truncate text-xs">v2.0.0</span>
+              </div>
+            </UiSidebarMenuButton>
+          </UiSidebarMenuItem>
+        </UiSidebarMenu>
+        <UiSidebarInput v-model="query" placeholder="Search the docs..." />
+      </UiSidebarHeader>
+      <UiSidebarContent>
+        <UiSidebarGroup v-for="group in filteredGroups" :key="group.label">
+          <UiSidebarGroupLabel>{{ group.label }}</UiSidebarGroupLabel>
+          <UiSidebarGroupContent>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem v-for="item in group.items" :key="item">
+                <UiSidebarMenuButton>{{ item }}</UiSidebarMenuButton>
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+          </UiSidebarGroupContent>
+        </UiSidebarGroup>
+      </UiSidebarContent>
+    </UiSidebar>
+    <UiSidebarInset>
+      <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+        <UiSidebarTrigger class="-ml-1" />
+        <span class="text-sm font-medium">API Documentation</span>
+      </header>
+    </UiSidebarInset>
+  </UiSidebarProvider>
+</template>`;
+
+/**
+ * Documentation-style sidebar with `UiSidebarInput` that filters navigation items across multiple groups (Models, Advanced, etc.).
+ * Uses `collapsible="offcanvas"` — the sidebar slides completely off screen when closed, since text-only items have no icon representation for icon-collapse mode.
+ */
+export const WithSearch: Story = {
+  render: (args) => ({
+    components: {
+      UiSidebar,
+      UiSidebarContent,
+      UiSidebarGroup,
+      UiSidebarGroupContent,
+      UiSidebarGroupLabel,
+      UiSidebarHeader,
+      UiSidebarInput,
+      UiSidebarInset,
+      UiSidebarMenu,
+      UiSidebarMenuButton,
+      UiSidebarMenuItem,
+      UiSidebarProvider,
+      UiSidebarTrigger,
+      Command,
+    },
+    setup() {
+      const groups = [
+        {
+          label: 'Getting Started',
+          items: ['Quick Start', 'Authentication', 'API Keys'],
+        },
+        {
+          label: 'Models',
+          items: ['Completions', 'Embeddings', 'Chat', 'Multimodal'],
+        },
+        {
+          label: 'Advanced',
+          items: ['Fine-tuning', 'Prompt Engineering', 'Evaluation', 'RAG'],
+        },
+      ];
+      const query = ref('');
+      const matchesQuery = (item: string) => item.toLowerCase().includes(query.value.toLowerCase());
+      const filteredGroups = computed(() =>
+        groups
+          .map((group) => ({ ...group, items: group.items.filter(matchesQuery) }))
+          .filter((group) => group.items.length > 0),
+      );
+      return { args, query, filteredGroups };
+    },
+    template: `
+      <UiSidebarProvider :default-open="true">
+        <UiSidebar :side="args.side" :variant="args.variant" :collapsible="args.collapsible">
+          <UiSidebarHeader>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem>
+                <UiSidebarMenuButton size="lg">
+                  <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                    <Command class="size-4" />
+                  </div>
+                  <div class="grid flex-1 text-left text-sm leading-tight">
+                    <span class="truncate font-semibold">API Docs</span>
+                    <span class="truncate text-xs">v2.0.0</span>
+                  </div>
+                </UiSidebarMenuButton>
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+            <UiSidebarInput v-model="query" placeholder="Search the docs..." class="group-data-[collapsible=icon]:hidden" />
+          </UiSidebarHeader>
+          <UiSidebarContent>
+            <UiSidebarGroup v-for="group in filteredGroups" :key="group.label">
+              <UiSidebarGroupLabel>{{ group.label }}</UiSidebarGroupLabel>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <UiSidebarMenuItem v-for="item in group.items" :key="item">
+                    <UiSidebarMenuButton>{{ item }}</UiSidebarMenuButton>
+                  </UiSidebarMenuItem>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+          </UiSidebarContent>
+        </UiSidebar>
+        <UiSidebarInset>
+          <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+            <UiSidebarTrigger class="-ml-1" />
+            <span class="text-sm font-medium">API Documentation</span>
+          </header>
+        </UiSidebarInset>
+      </UiSidebarProvider>
+    `,
+  }),
+  args: {
+    collapsible: 'offcanvas',
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withSearchTemplateSource,
+      },
+    },
+  },
+};
+
+const withActionsTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarGroup,
+  UiSidebarGroupAction,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarHeaderTrigger,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuAction,
+  UiSidebarMenuButton,
+  UiSidebarMenuItem,
+  UiSidebarProvider,
+  UiSidebarRail,
+  UiSidebarSeparator,
+} from '@aleph-alpha/ui-library'
+import { FlaskConical, MessageSquare, BarChart3, Database, Key, Activity, Settings, Command, Plus, MoreHorizontal } from 'lucide-vue-next'
+
+const pipelineItems = ref([
+  { title: 'Summarization', icon: FlaskConical },
+  { title: 'RAG Chatbot', icon: MessageSquare },
+  { title: 'Sentiment Analysis', icon: BarChart3 },
+  { title: 'Data Extraction', icon: Database },
+])
+
+let counter = 0
+function addPipeline() {
+  counter++
+  pipelineItems.value.push({ title: \\\`New Pipeline \\\${counter}\\\`, icon: FlaskConical })
+}
+
+const adminItems = [
+  { title: 'API Keys', icon: Key },
+  { title: 'Usage', icon: Activity },
+  { title: 'Settings', icon: Settings },
+]
+</script>
+
+<template>
+  <UiSidebarProvider :default-open="true">
+    <UiSidebar>
+      <UiSidebarHeaderTrigger>
+        <template #logo>
+          <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+            <Command class="size-4" />
+          </div>
+        </template>
+        <span class="truncate font-semibold">Acme AI</span>
+        <span class="truncate text-xs">Enterprise</span>
+      </UiSidebarHeaderTrigger>
+      <UiSidebarContent>
+        <UiSidebarGroup>
+          <UiSidebarGroupLabel>Pipelines</UiSidebarGroupLabel>
+          <UiSidebarGroupAction title="New Pipeline" @click="addPipeline">
+            <Plus />
+          </UiSidebarGroupAction>
+          <UiSidebarGroupContent>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem v-for="item in pipelineItems" :key="item.title">
+                <UiSidebarMenuButton :tooltip="item.title">
+                  <component :is="item.icon" />
+                  <span>{{ item.title }}</span>
+                </UiSidebarMenuButton>
+                <UiSidebarMenuAction :show-on-hover="true" title="More options">
+                  <MoreHorizontal />
+                </UiSidebarMenuAction>
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+          </UiSidebarGroupContent>
+        </UiSidebarGroup>
+        <UiSidebarSeparator />
+        <UiSidebarGroup>
+          <UiSidebarGroupLabel>Administration</UiSidebarGroupLabel>
+          <UiSidebarGroupContent>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem v-for="item in adminItems" :key="item.title">
+                <UiSidebarMenuButton :tooltip="item.title">
+                  <component :is="item.icon" />
+                  <span>{{ item.title }}</span>
+                </UiSidebarMenuButton>
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+          </UiSidebarGroupContent>
+        </UiSidebarGroup>
+      </UiSidebarContent>
+      <UiSidebarRail />
+    </UiSidebar>
+    <UiSidebarInset>
+      <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+        <span class="text-sm font-medium">Pipelines</span>
+      </header>
+    </UiSidebarInset>
+  </UiSidebarProvider>
+</template>`;
+
+/**
+ * Sidebar with `UiSidebarGroupAction` (a "+" button on the "Pipelines" group label), `UiSidebarMenuAction` (a "..." button on each pipeline item),
+ * and a `UiSidebarSeparator` dividing the "Pipelines" group from an "Administration" group.
+ * Menu actions use `show-on-hover` so they only appear when hovering the item. Both action types auto-hide in icon-collapse mode.
+ */
+export const WithActions: Story = {
+  render: (args) => ({
+    components: {
+      UiSidebar,
+      UiSidebarContent,
+      UiSidebarGroup,
+      UiSidebarGroupAction,
+      UiSidebarGroupContent,
+      UiSidebarGroupLabel,
+      UiSidebarHeaderTrigger,
+      UiSidebarInset,
+      UiSidebarMenu,
+      UiSidebarMenuAction,
+      UiSidebarMenuButton,
+      UiSidebarMenuItem,
+      UiSidebarProvider,
+      UiSidebarRail,
+      UiSidebarSeparator,
+      FlaskConical,
+      MessageSquare,
+      BarChart3,
+      Database,
+      Key,
+      Activity,
+      Settings,
+      Command,
+      Plus,
+      MoreHorizontal,
+    },
+    setup() {
+      const pipelineItems = ref([
+        { title: 'Summarization', icon: FlaskConical },
+        { title: 'RAG Chatbot', icon: MessageSquare },
+        { title: 'Sentiment Analysis', icon: BarChart3 },
+        { title: 'Data Extraction', icon: Database },
+      ]);
+      let counter = 0;
+      const addPipeline = () => {
+        counter++;
+        pipelineItems.value.push({ title: `New Pipeline ${counter}`, icon: FlaskConical });
+      };
+      const adminItems = [
+        { title: 'API Keys', icon: Key },
+        { title: 'Usage', icon: Activity },
+        { title: 'Settings', icon: Settings },
+      ];
+      return { args, pipelineItems, addPipeline, adminItems };
+    },
+    template: `
+      <UiSidebarProvider :default-open="true">
+        <UiSidebar :side="args.side" :variant="args.variant" :collapsible="args.collapsible">
+          <UiSidebarHeaderTrigger>
+            <template #logo>
+              <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                <Command class="size-4" />
+              </div>
+            </template>
+            <span class="truncate font-semibold">Acme AI</span>
+            <span class="truncate text-xs">Enterprise</span>
+          </UiSidebarHeaderTrigger>
+          <UiSidebarContent>
+            <UiSidebarGroup>
+              <UiSidebarGroupLabel>Pipelines</UiSidebarGroupLabel>
+              <UiSidebarGroupAction title="New Pipeline" @click="addPipeline">
+                <Plus />
+              </UiSidebarGroupAction>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <UiSidebarMenuItem v-for="item in pipelineItems" :key="item.title">
+                    <UiSidebarMenuButton :tooltip="item.title">
+                      <component :is="item.icon" />
+                      <span>{{ item.title }}</span>
+                    </UiSidebarMenuButton>
+                    <UiSidebarMenuAction :show-on-hover="true" title="More options">
+                      <MoreHorizontal />
+                    </UiSidebarMenuAction>
+                  </UiSidebarMenuItem>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+            <UiSidebarSeparator />
+            <UiSidebarGroup>
+              <UiSidebarGroupLabel>Administration</UiSidebarGroupLabel>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <UiSidebarMenuItem v-for="item in adminItems" :key="item.title">
+                    <UiSidebarMenuButton :tooltip="item.title">
+                      <component :is="item.icon" />
+                      <span>{{ item.title }}</span>
+                    </UiSidebarMenuButton>
+                  </UiSidebarMenuItem>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+          </UiSidebarContent>
+          <UiSidebarRail />
+        </UiSidebar>
+        <UiSidebarInset>
+          <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+            <span class="text-sm font-medium">Pipelines</span>
+          </header>
+        </UiSidebarInset>
+      </UiSidebarProvider>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withActionsTemplateSource,
+      },
+    },
+  },
+};
+
+const withSubmenuTemplateSource = `<script setup lang="ts">
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarGroup,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarHeaderTrigger,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuButton,
+  UiSidebarMenuItem,
+  UiSidebarMenuSub,
+  UiSidebarMenuSubButton,
+  UiSidebarMenuSubItem,
+  UiSidebarProvider,
+  UiSidebarRail,
+} from '@aleph-alpha/ui-library'
+import { CollapsibleRoot, CollapsibleContent, CollapsibleTrigger } from 'reka-ui'
+import { Bot, Database, BarChart3, MessageSquare, Command, ChevronRight } from 'lucide-vue-next'
+
+const navItems = [
+  {
+    title: 'Models',
+    icon: Database,
+    children: ['Completions', 'Embeddings', 'Chat', 'Multimodal'],
+  },
+  {
+    title: 'Evaluations',
+    icon: BarChart3,
+    children: ['Benchmarks', 'Custom Tests', 'Reports'],
+  },
+  {
+    title: 'Playground',
+    icon: Bot,
+    children: [],
+  },
+  {
+    title: 'Conversations',
+    icon: MessageSquare,
+    children: [],
+  },
+]
+</script>
+
+<template>
+  <UiSidebarProvider :default-open="true">
+    <UiSidebar>
+      <UiSidebarHeaderTrigger>
+        <template #logo>
+          <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+            <Command class="size-4" />
+          </div>
+        </template>
+        <span class="truncate font-semibold">Acme AI</span>
+        <span class="truncate text-xs">Enterprise</span>
+      </UiSidebarHeaderTrigger>
+      <UiSidebarContent>
+        <UiSidebarGroup>
+          <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+          <UiSidebarGroupContent>
+            <UiSidebarMenu>
+              <template v-for="item in navItems" :key="item.title">
+                <CollapsibleRoot v-if="item.children.length" as-child class="group/collapsible">
+                  <UiSidebarMenuItem>
+                    <CollapsibleTrigger as-child>
+                      <UiSidebarMenuButton :tooltip="item.title">
+                        <component :is="item.icon" />
+                        <span>{{ item.title }}</span>
+                        <ChevronRight class="ml-auto transition-transform group-data-[state=open]/collapsible:rotate-90" />
+                      </UiSidebarMenuButton>
+                    </CollapsibleTrigger>
+                    <CollapsibleContent>
+                      <UiSidebarMenuSub>
+                        <UiSidebarMenuSubItem v-for="child in item.children" :key="child">
+                          <UiSidebarMenuSubButton>{{ child }}</UiSidebarMenuSubButton>
+                        </UiSidebarMenuSubItem>
+                      </UiSidebarMenuSub>
+                    </CollapsibleContent>
+                  </UiSidebarMenuItem>
+                </CollapsibleRoot>
+                <UiSidebarMenuItem v-else>
+                  <UiSidebarMenuButton :tooltip="item.title">
+                    <component :is="item.icon" />
+                    <span>{{ item.title }}</span>
+                  </UiSidebarMenuButton>
+                </UiSidebarMenuItem>
+              </template>
+            </UiSidebarMenu>
+          </UiSidebarGroupContent>
+        </UiSidebarGroup>
+      </UiSidebarContent>
+      <UiSidebarRail />
+    </UiSidebar>
+    <UiSidebarInset>
+      <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+        <span class="text-sm font-medium">Platform</span>
+      </header>
+    </UiSidebarInset>
+  </UiSidebarProvider>
+</template>`;
+
+/**
+ * Sidebar with collapsible `UiSidebarMenuSub` submenus using `Collapsible` from reka-ui. "Models" and "Evaluations" expand to reveal nested items via `UiSidebarMenuSubButton`.
+ * Submenu items are hidden in icon-collapse mode. A chevron icon rotates to indicate the open/closed state.
+ */
+export const WithSubmenu: Story = {
+  render: (args) => ({
+    components: {
+      UiSidebar,
+      UiSidebarContent,
+      UiSidebarGroup,
+      UiSidebarGroupContent,
+      UiSidebarGroupLabel,
+      UiSidebarHeaderTrigger,
+      UiSidebarInset,
+      UiSidebarMenu,
+      UiSidebarMenuButton,
+      UiSidebarMenuItem,
+      UiSidebarMenuSub,
+      UiSidebarMenuSubButton,
+      UiSidebarMenuSubItem,
+      UiSidebarProvider,
+      UiSidebarRail,
+      CollapsibleRoot,
+      CollapsibleContent,
+      CollapsibleTrigger,
+      Bot,
+      Database,
+      BarChart3,
+      MessageSquare,
+      Command,
+      ChevronRight,
+    },
+    setup() {
+      const navItems = [
+        {
+          title: 'Models',
+          icon: Database,
+          children: ['Completions', 'Embeddings', 'Chat', 'Multimodal'],
+        },
+        {
+          title: 'Evaluations',
+          icon: BarChart3,
+          children: ['Benchmarks', 'Custom Tests', 'Reports'],
+        },
+        {
+          title: 'Playground',
+          icon: Bot,
+          children: [],
+        },
+        {
+          title: 'Conversations',
+          icon: MessageSquare,
+          children: [],
+        },
+      ];
+      return { args, navItems };
+    },
+    template: `
+      <UiSidebarProvider :default-open="true">
+        <UiSidebar :side="args.side" :variant="args.variant" :collapsible="args.collapsible">
+          <UiSidebarHeaderTrigger>
+            <template #logo>
+              <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                <Command class="size-4" />
+              </div>
+            </template>
+            <span class="truncate font-semibold">Acme AI</span>
+            <span class="truncate text-xs">Enterprise</span>
+          </UiSidebarHeaderTrigger>
+          <UiSidebarContent>
+            <UiSidebarGroup>
+              <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <template v-for="item in navItems" :key="item.title">
+                    <CollapsibleRoot v-if="item.children.length" as-child class="group/collapsible">
+                      <UiSidebarMenuItem>
+                        <CollapsibleTrigger as-child>
+                          <UiSidebarMenuButton :tooltip="item.title">
+                            <component :is="item.icon" />
+                            <span>{{ item.title }}</span>
+                            <ChevronRight class="ml-auto transition-transform group-data-[state=open]/collapsible:rotate-90" />
+                          </UiSidebarMenuButton>
+                        </CollapsibleTrigger>
+                        <CollapsibleContent>
+                          <UiSidebarMenuSub>
+                            <UiSidebarMenuSubItem v-for="child in item.children" :key="child">
+                              <UiSidebarMenuSubButton>{{ child }}</UiSidebarMenuSubButton>
+                            </UiSidebarMenuSubItem>
+                          </UiSidebarMenuSub>
+                        </CollapsibleContent>
+                      </UiSidebarMenuItem>
+                    </CollapsibleRoot>
+                    <UiSidebarMenuItem v-else>
+                      <UiSidebarMenuButton :tooltip="item.title">
+                        <component :is="item.icon" />
+                        <span>{{ item.title }}</span>
+                      </UiSidebarMenuButton>
+                    </UiSidebarMenuItem>
+                  </template>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+          </UiSidebarContent>
+          <UiSidebarRail />
+        </UiSidebar>
+        <UiSidebarInset>
+          <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+            <span class="text-sm font-medium">Platform</span>
+          </header>
+        </UiSidebarInset>
+      </UiSidebarProvider>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withSubmenuTemplateSource,
+      },
+    },
+  },
+};
+
+const withSkeletonTemplateSource = `<script setup lang="ts">
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarGroup,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuItem,
+  UiSidebarMenuSkeleton,
+  UiSidebarProvider,
+  UiSidebarRail,
+  UiSidebarTrigger,
+} from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiSidebarProvider :default-open="true">
+    <UiSidebar>
+      <UiSidebarContent>
+        <UiSidebarGroup>
+          <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+          <UiSidebarGroupContent>
+            <UiSidebarMenu>
+              <UiSidebarMenuItem v-for="i in 4" :key="i">
+                <UiSidebarMenuSkeleton :show-icon="true" />
+              </UiSidebarMenuItem>
+            </UiSidebarMenu>
+          </UiSidebarGroupContent>
+        </UiSidebarGroup>
+      </UiSidebarContent>
+      <UiSidebarRail />
+    </UiSidebar>
+    <UiSidebarInset>
+      <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+        <UiSidebarTrigger class="-ml-1" />
+        <span class="text-sm font-medium">Platform</span>
+      </header>
+    </UiSidebarInset>
+  </UiSidebarProvider>
+</template>`;
+
+/**
+ * Sidebar with `UiSidebarMenuSkeleton` placeholders showing a loading state.
+ * Use `show-icon` to include an icon-sized skeleton circle alongside the text bar. Each skeleton renders a random width for a natural staggered look.
+ */
+export const WithSkeleton: Story = {
+  render: (args) => ({
+    components: {
+      UiSidebar,
+      UiSidebarContent,
+      UiSidebarGroup,
+      UiSidebarGroupContent,
+      UiSidebarGroupLabel,
+      UiSidebarInset,
+      UiSidebarMenu,
+      UiSidebarMenuItem,
+      UiSidebarMenuSkeleton,
+      UiSidebarProvider,
+      UiSidebarRail,
+      UiSidebarTrigger,
+    },
+    setup() {
+      return { args };
+    },
+    template: `
+      <UiSidebarProvider :default-open="true">
+        <UiSidebar :side="args.side" :variant="args.variant" :collapsible="args.collapsible">
+          <UiSidebarContent>
+            <UiSidebarGroup>
+              <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <UiSidebarMenuItem v-for="i in 4" :key="i">
+                    <UiSidebarMenuSkeleton :show-icon="true" />
+                  </UiSidebarMenuItem>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+          </UiSidebarContent>
+          <UiSidebarRail />
+        </UiSidebar>
+        <UiSidebarInset>
+          <header class="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+            <UiSidebarTrigger class="-ml-1" />
+            <span class="text-sm font-medium">Platform</span>
+          </header>
+        </UiSidebarInset>
+      </UiSidebarProvider>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withSkeletonTemplateSource,
+      },
+    },
+  },
+};
+
+const programmaticControlTemplateSource = `<script setup lang="ts">
+import {
+  UiSidebar,
+  UiSidebarContent,
+  UiSidebarGroup,
+  UiSidebarGroupContent,
+  UiSidebarGroupLabel,
+  UiSidebarHeaderTrigger,
+  UiSidebarInset,
+  UiSidebarMenu,
+  UiSidebarMenuButton,
+  UiSidebarMenuItem,
+  UiSidebarProvider,
+  UiSidebarRail,
+  useSidebar,
+} from '@aleph-alpha/ui-library'
+import { Bot, Database, BarChart3, MessageSquare, Command } from 'lucide-vue-next'
+
+const items = [
+  { title: 'Playground', icon: Bot },
+  { title: 'Models', icon: Database },
+  { title: 'Evaluations', icon: BarChart3 },
+  { title: 'Conversations', icon: MessageSquare },
+]
+
+// useSidebar() must be called inside <UiSidebarProvider>.
+// Use a child component or <script setup> in a component nested within the provider.
+</script>
+
+<template>
+  <UiSidebarProvider>
+    <!-- Wrap content in a child component that calls useSidebar() -->
+    <SidebarLayout :items="items" />
+  </UiSidebarProvider>
+</template>
+
+<!-- Child component (e.g. SidebarLayout.vue) -->
+<script setup lang="ts">
+import { useSidebar } from '@aleph-alpha/ui-library'
+
+const { state, open, setOpen, toggleSidebar } = useSidebar()
+</script>
+
+<template>
+  <UiSidebar><!-- ... --></UiSidebar>
+  <UiSidebarInset>
+    <div class="p-6 space-y-4">
+      <p>Sidebar is <strong>{{ state }}</strong></p>
+      <button @click="toggleSidebar()">Toggle</button>
+      <button @click="setOpen(true)">Open</button>
+      <button @click="setOpen(false)">Close</button>
+    </div>
+  </UiSidebarInset>
+</template>`;
+
+/**
+ * Programmatic sidebar control via the `useSidebar()` composable. The composable must be called
+ * inside a component rendered within `<UiSidebarProvider>`. It returns reactive state (`state`, `open`)
+ * and methods (`toggleSidebar`, `setOpen`) to control the sidebar from anywhere in the provider tree.
+ *
+ * This is the recommended pattern for controlling the sidebar from outside — e.g. opening it
+ * from a toolbar button, closing it after navigation, or syncing state with a store.
+ */
+export const ProgrammaticControl: Story = {
+  render: (args) => ({
+    components: {
+      UiSidebar,
+      UiSidebarContent,
+      UiSidebarGroup,
+      UiSidebarGroupContent,
+      UiSidebarGroupLabel,
+      UiSidebarHeaderTrigger,
+      UiSidebarInset,
+      UiSidebarMenu,
+      UiSidebarMenuButton,
+      UiSidebarMenuItem,
+      UiSidebarProvider,
+      UiSidebarRail,
+      Bot,
+      Database,
+      BarChart3,
+      MessageSquare,
+      Command,
+      // Inline child component that uses useSidebar() — in real apps this would be a separate .vue file
+      SidebarContent: defineComponent({
+        setup() {
+          const { state, toggleSidebar, setOpen } = useSidebar();
+          return { state, toggleSidebar, setOpen };
+        },
+        template: `<slot :state="state" :toggleSidebar="toggleSidebar" :setOpen="setOpen" />`,
+      }),
+    },
+    setup() {
+      const items = [
+        { title: 'Playground', icon: Bot },
+        { title: 'Models', icon: Database },
+        { title: 'Evaluations', icon: BarChart3 },
+        { title: 'Conversations', icon: MessageSquare },
+      ];
+      return { args, items };
+    },
+    template: `
+      <UiSidebarProvider>
+        <UiSidebar :side="args.side" :variant="args.variant" :collapsible="args.collapsible">
+          <UiSidebarHeaderTrigger>
+            <template #logo>
+              <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                <Command class="size-4" />
+              </div>
+            </template>
+            <span class="truncate font-semibold">Acme AI</span>
+            <span class="truncate text-xs">Enterprise</span>
+          </UiSidebarHeaderTrigger>
+          <UiSidebarContent>
+            <UiSidebarGroup>
+              <UiSidebarGroupLabel>Platform</UiSidebarGroupLabel>
+              <UiSidebarGroupContent>
+                <UiSidebarMenu>
+                  <UiSidebarMenuItem v-for="item in items" :key="item.title">
+                    <UiSidebarMenuButton :tooltip="item.title">
+                      <component :is="item.icon" />
+                      <span>{{ item.title }}</span>
+                    </UiSidebarMenuButton>
+                  </UiSidebarMenuItem>
+                </UiSidebarMenu>
+              </UiSidebarGroupContent>
+            </UiSidebarGroup>
+          </UiSidebarContent>
+          <UiSidebarRail />
+        </UiSidebar>
+        <UiSidebarInset>
+          <SidebarContent v-slot="{ state, toggleSidebar, setOpen }">
+            <div class="p-6">
+              <div class="mb-6">
+                <h2 class="text-lg font-semibold mb-1">Programmatic Control</h2>
+                <p class="text-sm text-muted-foreground">
+                  Use <code class="rounded bg-muted px-1.5 py-0.5 text-xs">useSidebar()</code> inside the provider tree to control the sidebar from any component.
+                </p>
+              </div>
+              <div class="flex items-center gap-3 mb-6">
+                <span class="text-sm">State: <strong>{{ state }}</strong></span>
+              </div>
+              <div class="flex flex-wrap gap-2">
+                <button
+                  class="inline-flex items-center justify-center rounded-md text-sm font-medium h-9 px-4 border border-input bg-background hover:bg-accent hover:text-accent-foreground"
+                  @click="toggleSidebar()"
+                >
+                  Toggle sidebar
+                </button>
+                <button
+                  class="inline-flex items-center justify-center rounded-md text-sm font-medium h-9 px-4 border border-input bg-background hover:bg-accent hover:text-accent-foreground"
+                  @click="setOpen(true)"
+                >
+                  Open
+                </button>
+                <button
+                  class="inline-flex items-center justify-center rounded-md text-sm font-medium h-9 px-4 border border-input bg-background hover:bg-accent hover:text-accent-foreground"
+                  @click="setOpen(false)"
+                >
+                  Close
+                </button>
+              </div>
+            </div>
+          </SidebarContent>
+        </UiSidebarInset>
+      </UiSidebarProvider>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: programmaticControlTemplateSource,
+      },
+    },
+  },
+};