@aleph-alpha/ui-library 1.14.0 → 1.16.0

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

@@ -1,4 +1,4 @@
-import { ref, computed } from 'vue';
+import { ref, computed, defineComponent } from 'vue';
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
 import {
   UiSidebar,
@@ -25,6 +25,7 @@ import {
   UiSidebarRail,
   UiSidebarSeparator,
   UiSidebarTrigger,
+  useSidebar,
 } from '.';
 import { CollapsibleRoot, CollapsibleContent, CollapsibleTrigger } from 'reka-ui';
 import {
@@ -1008,3 +1009,180 @@ export const WithSkeleton: Story = {
     },
   },
 };
+
+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,
+      },
+    },
+  },
+};

package/src/components/UiSidebar/UiSidebarProvider.vue

@@ -7,12 +7,10 @@
   });
 
   const props = defineProps<UiSidebarProviderProps>();
-
-  const open = defineModel<boolean | undefined>('open');
 </script>
 
 <template>
-  <ShadcnSidebarProvider v-model:open="open" :default-open="props.defaultOpen">
+  <ShadcnSidebarProvider :default-open="props.defaultOpen">
     <slot />
   </ShadcnSidebarProvider>
 </template>

package/src/components/UiSidebar/types.ts

@@ -12,20 +12,17 @@ export type UiSidebarMenuButtonSize = 'default' | 'sm' | 'lg';
 
 export type UiSidebarMenuSubButtonSize = 'sm' | 'md';
 
+/**
+ * Wraps the sidebar and manages its open/closed state.
+ * Omit `default-open` to use cookie-based persistence (falls back to expanded).
+ */
 export interface UiSidebarProviderProps {
   /**
-   * The default open state when uncontrolled.
-   * If not provided, the core provider uses cookie-based persistence
+   * The initial open state of the sidebar.
+   * If not provided, the inner provider uses cookie-based persistence
    * (falls back to expanded if no cookie exists).
    */
   defaultOpen?: boolean;
-
-  /**
-   * The controlled open state of the sidebar.
-   * - Omit for uncontrolled mode (component manages state internally)
-   * - Use `v-model:open` for controlled mode
-   */
-  open?: boolean;
 }
 
 /**

package/src/components/UiStepper/UiStepper.stories.ts

@@ -12,7 +12,7 @@ import {
 import { UiIcon } from '../UiIcon';
 
 const meta: Meta<typeof UiStepper> = {
-  title: 'Primitives/UiStepper',
+  title: 'Components/UiStepper',
   component: UiStepper,
   tags: ['autodocs'],
   argTypes: {

package/src/components/core/calendar/Calendar.vue

@@ -184,7 +184,7 @@
       <CalendarGrid v-for="month in grid" :key="month.value.toString()">
         <CalendarGridHead>
           <CalendarGridRow>
-            <CalendarHeadCell v-for="day in weekDays" :key="day">
+            <CalendarHeadCell v-for="(day, i) in weekDays" :key="i">
               {{ day }}
             </CalendarHeadCell>
           </CalendarGridRow>

package/src/components/core/range-calendar/RangeCalendar.vue

@@ -47,7 +47,7 @@
       <RangeCalendarGrid v-for="month in grid" :key="month.value.toString()">
         <RangeCalendarGridHead>
           <RangeCalendarGridRow>
-            <RangeCalendarHeadCell v-for="day in weekDays" :key="day">
+            <RangeCalendarHeadCell v-for="(day, i) in weekDays" :key="i">
               {{ day }}
             </RangeCalendarHeadCell>
           </RangeCalendarGridRow>

package/src/patterns/UiDatePicker/UiDatePicker.stories.ts

@@ -39,7 +39,7 @@ const meta: Meta<typeof UiDatePicker> = {
     weekStartsOn: {
       control: 'select',
       options: [0, 1, 2, 3, 4, 5, 6],
-      description: 'The day of the week to start on. 0 = Sunday, 1 = Monday, etc.',
+      description: 'The day of the week to start on. 0 is the locale default first day.',
     },
     numberOfMonths: {
       control: { type: 'number', min: 1, max: 3 },
@@ -369,7 +369,6 @@ const date = ref<DateValue>()
   <UiDatePicker
     v-model="date"
     locale="de"
-    :week-starts-on="1"
     weekday-format="short"
     placeholder="Datum auswählen"
   />
@@ -382,7 +381,6 @@ const date = ref<DateValue>()
 export const GermanLocale: Story = {
   args: {
     locale: 'de',
-    weekStartsOn: 1,
     weekdayFormat: 'short',
     placeholder: 'Datum auswählen',
   },
@@ -395,7 +393,6 @@ export const GermanLocale: Story = {
     template: `<UiDatePicker
       v-model="date"
       :locale="args.locale"
-      :week-starts-on="args.weekStartsOn"
       :weekday-format="args.weekdayFormat"
       :placeholder="args.placeholder"
       :disabled="args.disabled"

package/src/patterns/UiDatePicker/types.ts

@@ -125,7 +125,7 @@ export interface UiDatePickerProps {
 
   /**
    * The day of the week to start on.
-   * @default 0 (Sunday)
+   * @default 0
    */
   weekStartsOn?: UiDatePickerWeekStartsOn;