@aleph-alpha/ui-library 1.12.0 → 1.14.0

package/src/components/UiItem/UiItem.stories.ts

@@ -0,0 +1,1029 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiItem from './UiItem.vue';
+import {
+  UiItemGroup,
+  UiItemSeparator,
+  UiItemMedia,
+  UiItemContent,
+  UiItemTitle,
+  UiItemDescription,
+  UiItemActions,
+  UiItemHeader,
+  UiItemFooter,
+} from './index';
+
+import { ItemVariants, ItemSizes } from './constants';
+import { UiIcon } from '../UiIcon';
+import { UiButton } from '../UiButton';
+import { UiAvatar, UiAvatarImage, UiAvatarFallback } from '../UiAvatar';
+
+const meta: Meta<typeof UiItem> = {
+  title: 'Components/UiItem',
+  component: UiItem,
+  subcomponents: {
+    UiItemGroup,
+    UiItemSeparator,
+    UiItemMedia,
+    UiItemContent,
+    UiItemTitle,
+    UiItemDescription,
+    UiItemActions,
+    UiItemHeader,
+    UiItemFooter,
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ItemVariants,
+      description:
+        'The visual style of the item. Use `default` for standard styling, `outline` for bordered appearance, or `muted` for subdued secondary content.',
+    },
+    size: {
+      control: 'select',
+      options: ItemSizes,
+      description:
+        'The size of the item. Use `default` for standard spacing or `sm` for compact dense layouts.',
+    },
+    asChild: {
+      control: 'boolean',
+      description:
+        'Whether to render as a child element using Radix asChild pattern. Useful for rendering as links or custom components while preserving hover/focus states.',
+    },
+  },
+  args: {
+    variant: 'default',
+    size: 'default',
+    asChild: false,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiItem>;
+
+/**
+ * ## Basic Item
+ *
+ * The most basic usage of the Item component. It displays a title, description,
+ * and an action button in a flexible layout. This is the foundation for building
+ * more complex item patterns.
+ *
+ * **Key features demonstrated:**
+ * - `UiItemContent` wraps the title and description
+ * - `UiItemTitle` displays the main heading
+ * - `UiItemDescription` shows supporting text
+ * - `UiItemActions` contains interactive elements
+ */
+export const Basic: Story = {
+  render: (args) => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemActions,
+      UiButton,
+    },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItem v-bind="args" variant="outline">
+          <UiItemContent>
+            <UiItemTitle>Basic Item</UiItemTitle>
+            <UiItemDescription>
+              A simple item with title and description.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton variant="outline" size="sm">Action</UiButton>
+          </UiItemActions>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## Variants
+ *
+ * The Item component supports three visual variants to match different UI contexts:
+ *
+ * - **Default**: Standard styling with subtle background. Best for primary content areas.
+ * - **Outline**: Clear bordered style with transparent background. Ideal for lists and menus.
+ * - **Muted**: Subdued appearance for secondary or less important content.
+ *
+ * Choose the variant that best fits your design context and content hierarchy.
+ */
+export const Variants: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemActions,
+      UiButton,
+    },
+    template: `
+      <div class="flex flex-col gap-4 w-full max-w-lg">
+        <UiItem>
+          <UiItemContent>
+            <UiItemTitle>Default Variant</UiItemTitle>
+            <UiItemDescription>
+              Standard styling with subtle background and borders.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton variant="outline" size="sm">Open</UiButton>
+          </UiItemActions>
+        </UiItem>
+        
+        <UiItem variant="outline">
+          <UiItemContent>
+            <UiItemTitle>Outline Variant</UiItemTitle>
+            <UiItemDescription>
+              Outlined style with clear borders and transparent background.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton variant="outline" size="sm">Open</UiButton>
+          </UiItemActions>
+        </UiItem>
+        
+        <UiItem variant="muted">
+          <UiItemContent>
+            <UiItemTitle>Muted Variant</UiItemTitle>
+            <UiItemDescription>
+              Subdued appearance with muted colors for secondary content.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton variant="outline" size="sm">Open</UiButton>
+          </UiItemActions>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## Sizes
+ *
+ * The Item component supports two sizes for different layout needs:
+ *
+ * - **Default**: Standard size with comfortable padding (p-3). Use for primary content.
+ * - **Small (sm)**: Compact size with reduced padding (p-2). Perfect for dense lists,
+ *   menus, or when space is limited.
+ *
+ * The small size is particularly useful for notification items, dropdown menus,
+ * or navigation lists where you need to display many items in a limited space.
+ */
+export const Sizes: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemActions,
+      UiItemMedia,
+      UiButton,
+      UiIcon,
+    },
+    template: `
+      <div class="flex flex-col gap-4 w-full max-w-md">
+        <UiItem variant="outline">
+          <UiItemContent>
+            <UiItemTitle>Default Size Item</UiItemTitle>
+            <UiItemDescription>
+              Standard padding for comfortable spacing.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton variant="outline" size="sm">Action</UiButton>
+          </UiItemActions>
+        </UiItem>
+        
+        <UiItem variant="outline" size="sm">
+          <UiItemMedia variant="icon">
+            <UiIcon name="badge-check" :size="20" />
+          </UiItemMedia>
+          <UiItemContent>
+            <UiItemTitle>Small Size Item</UiItemTitle>
+          </UiItemContent>
+          <UiItemActions>
+            <UiIcon name="chevron-right" :size="16" />
+          </UiItemActions>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## With Icon
+ *
+ * Use `UiItemMedia` with `variant="icon"` to display an icon at the start of the item.
+ * This is perfect for notification items, settings entries, or any content that
+ * benefits from visual categorization.
+ *
+ * **Best practices:**
+ * - Use meaningful icons that reinforce the content
+ * - Keep icon colors consistent with the design system
+ * - Consider using different icon variants (outlined/filled) for visual hierarchy
+ */
+export const WithIcon: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemActions,
+      UiItemMedia,
+      UiButton,
+      UiIcon,
+    },
+    template: `
+      <div class="w-full max-w-lg">
+        <UiItem variant="outline">
+          <UiItemMedia variant="icon">
+            <UiIcon name="shield-alert" :size="20" />
+          </UiItemMedia>
+          <UiItemContent>
+            <UiItemTitle>Security Alert</UiItemTitle>
+            <UiItemDescription>
+              New login detected from unknown device.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton size="sm" variant="outline">Review</UiButton>
+          </UiItemActions>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## With Avatar
+ *
+ * Use `UiItemMedia` with the default variant to display avatars or profile images.
+ * This pattern is ideal for user lists, contact directories, or any content
+ * that represents a person or entity.
+ *
+ * **Use cases:**
+ * - User/team member lists
+ * - Contact directories
+ * - Comment threads
+ * - Notification items showing who triggered an action
+ */
+export const WithAvatar: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+      UiAvatar,
+      UiAvatarImage,
+      UiAvatarFallback,
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItem variant="outline">
+          <UiItemMedia>
+            <UiAvatar>
+              <UiAvatarImage src="https://github.com/shadcn.png" />
+              <UiAvatarFallback>SC</UiAvatarFallback>
+            </UiAvatar>
+          </UiItemMedia>
+          <UiItemContent>
+            <UiItemTitle>shadcn</UiItemTitle>
+            <UiItemDescription>Last seen 5 months ago</UiItemDescription>
+          </UiItemContent>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## With Image
+ *
+ * Use `UiItemMedia` with `variant="image"` to display images or thumbnails.
+ * The image variant provides appropriate sizing and rounded corners for
+ * visual content.
+ *
+ * **Use cases:**
+ * - Product listings
+ * - Media galleries
+ * - Article/blog post previews
+ * - File browser with thumbnails
+ */
+export const WithImage: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItem variant="outline">
+          <UiItemMedia variant="image">
+            <img 
+              src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=100&h=100&fit=crop" 
+              alt="Mountain landscape"
+              class="size-full object-cover"
+            />
+          </UiItemMedia>
+          <UiItemContent>
+            <UiItemTitle>Mountain Expedition</UiItemTitle>
+            <UiItemDescription>
+              Explore the breathtaking alpine landscapes.
+            </UiItemDescription>
+          </UiItemContent>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## Item Group
+ *
+ * Use `UiItemGroup` to group related items together with consistent styling.
+ * Add `UiItemSeparator` between items to create visual separation.
+ *
+ * **Key features:**
+ * - `UiItemGroup` provides consistent spacing between items
+ * - `UiItemSeparator` creates a subtle divider line
+ * - Great for settings panels, menus, and navigation lists
+ *
+ * **Best practices:**
+ * - Group logically related items together
+ * - Use separators sparingly to avoid visual clutter
+ * - Consider using headers to label different groups
+ */
+export const Group: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemGroup,
+      UiItemSeparator,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+      UiItemActions,
+      UiIcon,
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItemGroup class="rounded-lg border p-2">
+          <UiItem>
+            <UiItemMedia variant="icon">
+              <UiIcon name="user" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>Profile</UiItemTitle>
+              <UiItemDescription>Manage your profile settings</UiItemDescription>
+            </UiItemContent>
+            <UiItemActions>
+              <UiIcon name="chevron-right" :size="16" />
+            </UiItemActions>
+          </UiItem>
+          
+          <UiItemSeparator />
+          
+          <UiItem>
+            <UiItemMedia variant="icon">
+              <UiIcon name="bell" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>Notifications</UiItemTitle>
+              <UiItemDescription>Configure notification preferences</UiItemDescription>
+            </UiItemContent>
+            <UiItemActions>
+              <UiIcon name="chevron-right" :size="16" />
+            </UiItemActions>
+          </UiItem>
+          
+          <UiItemSeparator />
+          
+          <UiItem>
+            <UiItemMedia variant="icon">
+              <UiIcon name="settings" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>Settings</UiItemTitle>
+              <UiItemDescription>App preferences and configuration</UiItemDescription>
+            </UiItemContent>
+            <UiItemActions>
+              <UiIcon name="chevron-right" :size="16" />
+            </UiItemActions>
+          </UiItem>
+        </UiItemGroup>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## With Header and Footer
+ *
+ * Use `UiItemHeader` and `UiItemFooter` to add contextual information above
+ * and below the main content. This is useful for categorization, metadata,
+ * or additional details.
+ *
+ * **Use cases:**
+ * - File listings with type labels and metadata
+ * - Activity feeds with timestamps
+ * - Product cards with category and price info
+ * - Notification items with time and source
+ */
+export const WithHeaderAndFooter: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemHeader,
+      UiItemFooter,
+      UiItemMedia,
+      UiIcon,
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItem variant="outline">
+          <UiItemMedia variant="icon">
+            <UiIcon name="file-text" :size="20" />
+          </UiItemMedia>
+          <UiItemContent>
+            <UiItemHeader>DOCUMENT</UiItemHeader>
+            <UiItemTitle>Project Proposal.pdf</UiItemTitle>
+            <UiItemDescription>
+              Final version of the Q4 project proposal
+            </UiItemDescription>
+            <UiItemFooter>Updated 2 hours ago • 2.4 MB</UiItemFooter>
+          </UiItemContent>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## As Link
+ *
+ * Use the `as-child` prop to render the item as a custom element like an anchor tag.
+ * The hover and focus states will be applied to the anchor element, making
+ * the entire item clickable.
+ *
+ * **Key benefits:**
+ * - Semantic HTML with proper `<a>` tags
+ * - Full keyboard navigation support
+ * - Screen reader friendly
+ * - Proper link behavior (right-click, cmd+click, etc.)
+ *
+ * **Use cases:**
+ * - Navigation menus
+ * - Resource links
+ * - External links (with appropriate icons)
+ */
+export const AsLink: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemActions,
+      UiIcon,
+    },
+    template: `
+      <div class="flex flex-col gap-4 w-full max-w-md">
+        <UiItem as-child>
+          <a href="#">
+            <UiItemContent>
+              <UiItemTitle>Visit our documentation</UiItemTitle>
+              <UiItemDescription>
+                Learn how to get started with our components.
+              </UiItemDescription>
+            </UiItemContent>
+            <UiItemActions>
+              <UiIcon name="chevron-right" :size="16" />
+            </UiItemActions>
+          </a>
+        </UiItem>
+        
+        <UiItem variant="outline" as-child>
+          <a href="#" target="_blank" rel="noopener noreferrer">
+            <UiItemContent>
+              <UiItemTitle>External resource</UiItemTitle>
+              <UiItemDescription>
+                Opens in a new tab with security attributes.
+              </UiItemDescription>
+            </UiItemContent>
+            <UiItemActions>
+              <UiIcon name="external-link" :size="16" />
+            </UiItemActions>
+          </a>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## Team Members List
+ *
+ * A practical example showing a list of team members with avatars.
+ * This pattern combines avatars with user information and action buttons.
+ *
+ * **Common variations:**
+ * - Add online/offline status indicators
+ * - Include role badges
+ * - Add dropdown menus for more actions
+ * - Show last activity time
+ */
+export const TeamMembersList: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemGroup,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+      UiItemActions,
+      UiAvatar,
+      UiAvatarImage,
+      UiAvatarFallback,
+      UiButton,
+    },
+    setup() {
+      const teamMembers = [
+        {
+          name: 'Sarah Chen',
+          role: 'Engineering Lead',
+          avatar: 'https://i.pravatar.cc/150?u=sarah',
+        },
+        {
+          name: 'Marcus Johnson',
+          role: 'Senior Developer',
+          avatar: 'https://i.pravatar.cc/150?u=marcus',
+        },
+        {
+          name: 'Emily Rodriguez',
+          role: 'UX Designer',
+          avatar: 'https://i.pravatar.cc/150?u=emily',
+        },
+      ];
+      return { teamMembers };
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItemGroup class="rounded-lg border">
+          <UiItem v-for="member in teamMembers" :key="member.name" size="sm" class="p-3">
+            <UiItemMedia>
+              <UiAvatar>
+                <UiAvatarImage :src="member.avatar" />
+                <UiAvatarFallback>{{ member.name.split(' ').map(n => n[0]).join('') }}</UiAvatarFallback>
+              </UiAvatar>
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>{{ member.name }}</UiItemTitle>
+              <UiItemDescription>{{ member.role }}</UiItemDescription>
+            </UiItemContent>
+            <UiItemActions>
+              <UiButton variant="outline" size="sm">Message</UiButton>
+            </UiItemActions>
+          </UiItem>
+        </UiItemGroup>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## Notification List
+ *
+ * A notification center pattern showing different types of notifications
+ * with color-coded icons, timestamps, and read/unread states.
+ *
+ * **Features demonstrated:**
+ * - Color-coded icons for different notification types
+ * - Footer with timestamps
+ * - Muted variant for read notifications
+ * - Separators between items
+ */
+export const NotificationList: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemGroup,
+      UiItemSeparator,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+      UiItemFooter,
+      UiIcon,
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItemGroup class="rounded-lg border p-2">
+          <UiItem>
+            <UiItemMedia variant="icon" class="text-blue-500">
+              <UiIcon name="mail" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>New message from Sarah</UiItemTitle>
+              <UiItemDescription>Hey, can you review the latest PR?</UiItemDescription>
+              <UiItemFooter>2 minutes ago</UiItemFooter>
+            </UiItemContent>
+          </UiItem>
+          
+          <UiItemSeparator />
+          
+          <UiItem>
+            <UiItemMedia variant="icon" class="text-yellow-500">
+              <UiIcon name="alert-circle" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>System warning</UiItemTitle>
+              <UiItemDescription>Your storage is almost full (95% used)</UiItemDescription>
+              <UiItemFooter>1 hour ago</UiItemFooter>
+            </UiItemContent>
+          </UiItem>
+          
+          <UiItemSeparator />
+          
+          <UiItem variant="muted">
+            <UiItemMedia variant="icon" class="text-green-500">
+              <UiIcon name="check-circle" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemTitle>Deployment successful</UiItemTitle>
+              <UiItemDescription>v2.4.1 deployed to production</UiItemDescription>
+              <UiItemFooter>Yesterday</UiItemFooter>
+            </UiItemContent>
+          </UiItem>
+        </UiItemGroup>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## Empty State with Invite
+ *
+ * An empty state pattern using the Item component. Perfect for showing
+ * a call-to-action when a list is empty.
+ *
+ * **Use cases:**
+ * - Empty team member lists
+ * - No notifications state
+ * - Empty file lists
+ * - First-time user experiences
+ */
+export const EmptyStateWithInvite: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+      UiItemActions,
+      UiButton,
+      UiAvatar,
+      UiAvatarFallback,
+      UiIcon,
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <UiItem variant="outline">
+          <UiItemMedia>
+            <UiAvatar class="bg-muted">
+              <UiAvatarFallback>
+                <UiIcon name="users" :size="20" class="text-muted-foreground" />
+              </UiAvatarFallback>
+            </UiAvatar>
+          </UiItemMedia>
+          <UiItemContent>
+            <UiItemTitle>No Team Members</UiItemTitle>
+            <UiItemDescription>
+              Invite your team to collaborate on this project.
+            </UiItemDescription>
+          </UiItemContent>
+          <UiItemActions>
+            <UiButton size="sm">Invite</UiButton>
+          </UiItemActions>
+        </UiItem>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * ## All States
+ *
+ * A comprehensive showcase of all Item component states and variations
+ * in a single view. This is useful for:
+ *
+ * - **Visual QA**: Quickly verify all states look correct
+ * - **Design review**: See all variations side by side
+ * - **Documentation**: Reference for available options
+ *
+ * ### Variants
+ * - Default, Outline, Muted
+ *
+ * ### Sizes
+ * - Default, Small
+ *
+ * ### Media Variants
+ * - Default (avatar), Icon, Image
+ *
+ * ### Sub-components
+ * - UiItemGroup, UiItemSeparator
+ * - UiItemMedia, UiItemContent
+ * - UiItemTitle, UiItemDescription
+ * - UiItemActions, UiItemHeader, UiItemFooter
+ */
+export const AllStates: Story = {
+  render: () => ({
+    components: {
+      UiItem,
+      UiItemGroup,
+      UiItemSeparator,
+      UiItemContent,
+      UiItemTitle,
+      UiItemDescription,
+      UiItemMedia,
+      UiItemActions,
+      UiItemHeader,
+      UiItemFooter,
+      UiButton,
+      UiAvatar,
+      UiAvatarImage,
+      UiAvatarFallback,
+      UiIcon,
+    },
+    template: `
+      <div class="flex flex-col gap-8 w-full max-w-2xl">
+        <!-- VARIANTS SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">Variants</h3>
+          <div class="flex flex-col gap-3">
+            <UiItem>
+              <UiItemContent>
+                <UiItemTitle>Default Variant</UiItemTitle>
+                <UiItemDescription>Standard styling with subtle background</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+            
+            <UiItem variant="outline">
+              <UiItemContent>
+                <UiItemTitle>Outline Variant</UiItemTitle>
+                <UiItemDescription>Bordered style with transparent background</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+            
+            <UiItem variant="muted">
+              <UiItemContent>
+                <UiItemTitle>Muted Variant</UiItemTitle>
+                <UiItemDescription>Subdued appearance for secondary content</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+          </div>
+        </section>
+        
+        <!-- SIZES SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">Sizes</h3>
+          <div class="flex flex-col gap-3">
+            <UiItem variant="outline">
+              <UiItemMedia variant="icon">
+                <UiIcon name="layout-grid" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Default Size</UiItemTitle>
+                <UiItemDescription>Comfortable padding for primary content</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+            
+            <UiItem variant="outline" size="sm">
+              <UiItemMedia variant="icon">
+                <UiIcon name="layout-list" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Small Size</UiItemTitle>
+                <UiItemDescription>Compact padding for dense layouts</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+          </div>
+        </section>
+        
+        <!-- MEDIA VARIANTS SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">Media Variants</h3>
+          <div class="flex flex-col gap-3">
+            <UiItem variant="outline">
+              <UiItemMedia>
+                <UiAvatar>
+                  <UiAvatarImage src="https://i.pravatar.cc/150?u=demo" />
+                  <UiAvatarFallback>DM</UiAvatarFallback>
+                </UiAvatar>
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Default Media (Avatar)</UiItemTitle>
+                <UiItemDescription>Standard sizing for avatars</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+            
+            <UiItem variant="outline">
+              <UiItemMedia variant="icon">
+                <UiIcon name="star" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Icon Media</UiItemTitle>
+                <UiItemDescription>Compact sizing for icons</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+            
+            <UiItem variant="outline">
+              <UiItemMedia variant="image">
+                <img 
+                  src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=100&h=100&fit=crop" 
+                  alt="Demo image"
+                  class="size-full object-cover"
+                />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Image Media</UiItemTitle>
+                <UiItemDescription>Larger sizing for thumbnails</UiItemDescription>
+              </UiItemContent>
+            </UiItem>
+          </div>
+        </section>
+        
+        <!-- WITH ACTIONS SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">With Actions</h3>
+          <div class="flex flex-col gap-3">
+            <UiItem variant="outline">
+              <UiItemMedia variant="icon">
+                <UiIcon name="folder" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>With Button Action</UiItemTitle>
+                <UiItemDescription>Click the button to perform an action</UiItemDescription>
+              </UiItemContent>
+              <UiItemActions>
+                <UiButton variant="outline" size="sm">Action</UiButton>
+              </UiItemActions>
+            </UiItem>
+            
+            <UiItem variant="outline">
+              <UiItemMedia variant="icon">
+                <UiIcon name="file" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>With Icon Action</UiItemTitle>
+                <UiItemDescription>Navigate to see more details</UiItemDescription>
+              </UiItemContent>
+              <UiItemActions>
+                <UiIcon name="chevron-right" :size="16" />
+              </UiItemActions>
+            </UiItem>
+            
+            <UiItem variant="outline">
+              <UiItemMedia variant="icon">
+                <UiIcon name="inbox" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>With Multiple Actions</UiItemTitle>
+                <UiItemDescription>Multiple buttons in actions area</UiItemDescription>
+              </UiItemContent>
+              <UiItemActions>
+                <UiButton variant="ghost" size="sm">Cancel</UiButton>
+                <UiButton size="sm">Confirm</UiButton>
+              </UiItemActions>
+            </UiItem>
+          </div>
+        </section>
+        
+        <!-- WITH HEADER AND FOOTER SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">With Header and Footer</h3>
+          <UiItem variant="outline">
+            <UiItemMedia variant="icon">
+              <UiIcon name="calendar" :size="20" />
+            </UiItemMedia>
+            <UiItemContent>
+              <UiItemHeader>SCHEDULED EVENT</UiItemHeader>
+              <UiItemTitle>Team Standup Meeting</UiItemTitle>
+              <UiItemDescription>Daily sync with the engineering team</UiItemDescription>
+              <UiItemFooter>Tomorrow at 9:00 AM • 30 min</UiItemFooter>
+            </UiItemContent>
+            <UiItemActions>
+              <UiButton variant="outline" size="sm">Join</UiButton>
+            </UiItemActions>
+          </UiItem>
+        </section>
+        
+        <!-- GROUPED ITEMS SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">Grouped Items with Separator</h3>
+          <UiItemGroup class="rounded-lg border p-2">
+            <UiItem>
+              <UiItemMedia variant="icon">
+                <UiIcon name="home" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Dashboard</UiItemTitle>
+              </UiItemContent>
+              <UiItemActions>
+                <UiIcon name="chevron-right" :size="16" />
+              </UiItemActions>
+            </UiItem>
+            
+            <UiItemSeparator />
+            
+            <UiItem>
+              <UiItemMedia variant="icon">
+                <UiIcon name="bar-chart-2" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Analytics</UiItemTitle>
+              </UiItemContent>
+              <UiItemActions>
+                <UiIcon name="chevron-right" :size="16" />
+              </UiItemActions>
+            </UiItem>
+            
+            <UiItemSeparator />
+            
+            <UiItem>
+              <UiItemMedia variant="icon">
+                <UiIcon name="cog" :size="20" />
+              </UiItemMedia>
+              <UiItemContent>
+                <UiItemTitle>Settings</UiItemTitle>
+              </UiItemContent>
+              <UiItemActions>
+                <UiIcon name="chevron-right" :size="16" />
+              </UiItemActions>
+            </UiItem>
+          </UiItemGroup>
+        </section>
+        
+        <!-- AS LINK SECTION -->
+        <section>
+          <h3 class="text-lg font-semibold mb-4">As Link (as-child)</h3>
+          <div class="flex flex-col gap-3">
+            <UiItem as-child>
+              <a href="#" class="flex items-center gap-3">
+                <UiItemMedia variant="icon">
+                  <UiIcon name="link" :size="20" />
+                </UiItemMedia>
+                <UiItemContent>
+                  <UiItemTitle>Internal Link</UiItemTitle>
+                  <UiItemDescription>Rendered as an anchor tag</UiItemDescription>
+                </UiItemContent>
+                <UiItemActions>
+                  <UiIcon name="chevron-right" :size="16" />
+                </UiItemActions>
+              </a>
+            </UiItem>
+            
+            <UiItem variant="outline" as-child>
+              <a href="#" target="_blank" rel="noopener noreferrer" class="flex items-center gap-3">
+                <UiItemMedia variant="icon">
+                  <UiIcon name="external-link" :size="20" />
+                </UiItemMedia>
+                <UiItemContent>
+                  <UiItemTitle>External Link</UiItemTitle>
+                  <UiItemDescription>Opens in new tab</UiItemDescription>
+                </UiItemContent>
+                <UiItemActions>
+                  <UiIcon name="arrow-up-right" :size="16" />
+                </UiItemActions>
+              </a>
+            </UiItem>
+          </div>
+        </section>
+      </div>
+    `,
+  }),
+};