@stacksjs/components 0.2.3

package/src/ui/sidebar/SidebarHeader.stx

@@ -0,0 +1,100 @@
+<script>
+/**
+ * SidebarHeader Component
+ *
+ * A header component for the sidebar with logo, title, and optional search.
+ *
+ * @example
+ * <SidebarHeader
+ *   title="My App"
+ *   subtitle="Professional"
+ *   :showSearch="true"
+ * />
+ */
+
+// Props
+export const title = $props.title || ''
+export const subtitle = $props.subtitle || ''
+export const logo = $props.logo || ''
+export const logoIcon = $props.logoIcon || ''
+export const showSearch = $props.showSearch ?? false
+export const searchPlaceholder = $props.searchPlaceholder || 'Search...'
+export const searchValue = $props.searchValue || ''
+export const collapsed = $props.collapsed ?? false
+export const onSearch = $props.onSearch
+
+// Handle search input
+function handleSearchInput(event) {
+  if (onSearch) {
+    onSearch(event.target.value)
+  }
+}
+</script>
+
+<div class="flex-shrink-0">
+  <!-- Title bar area -->
+  <div class="h-13 flex items-center justify-between px-4 border-b border-black/5 dark:border-white/10">
+    @if(!collapsed)
+      <div class="flex items-center gap-3 min-w-0">
+        <!-- Logo -->
+        @if(logo)
+          <img src="{{ logo }}" alt="{{ title }}" class="w-8 h-8 rounded-lg object-cover" />
+        @elseif(logoIcon)
+          <div class="w-8 h-8 rounded-lg bg-gradient-to-br from-blue-500 to-blue-600 flex items-center justify-center">
+            <div class="{{ logoIcon }} w-5 h-5 text-white"></div>
+          </div>
+        @else
+          <div class="w-8 h-8 rounded-lg bg-gradient-to-br from-blue-500 to-blue-600 flex items-center justify-center text-white font-bold text-sm">
+            {{ title.charAt(0) }}
+          </div>
+        @endif
+
+        <!-- Title & Subtitle -->
+        <div class="min-w-0">
+          @if(title)
+            <div class="text-sm font-semibold text-black/90 dark:text-white truncate">
+              {{ title }}
+            </div>
+          @endif
+          @if(subtitle)
+            <div class="text-xs text-black/50 dark:text-white/50 truncate">
+              {{ subtitle }}
+            </div>
+          @endif
+        </div>
+      </div>
+    @else
+      <!-- Collapsed state - just logo -->
+      @if(logo)
+        <img src="{{ logo }}" alt="{{ title }}" class="w-8 h-8 rounded-lg object-cover mx-auto" />
+      @elseif(logoIcon)
+        <div class="w-8 h-8 rounded-lg bg-gradient-to-br from-blue-500 to-blue-600 flex items-center justify-center mx-auto">
+          <div class="{{ logoIcon }} w-5 h-5 text-white"></div>
+        </div>
+      @else
+        <div class="w-8 h-8 rounded-lg bg-gradient-to-br from-blue-500 to-blue-600 flex items-center justify-center text-white font-bold text-sm mx-auto">
+          {{ title.charAt(0) }}
+        </div>
+      @endif
+    @endif
+
+    <!-- Slot for custom header actions -->
+    <slot name="actions" />
+  </div>
+
+  <!-- Search (only when expanded) -->
+  @if(showSearch && !collapsed)
+    <div class="px-3 py-3">
+      <div class="relative">
+        <div class="i-hugeicons-search-01 absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-black/40 dark:text-white/40"></div>
+        <input
+          type="text"
+          placeholder="{{ searchPlaceholder }}"
+          value="{{ searchValue }}"
+          class="w-full pl-9 pr-3 py-2 text-sm bg-black/5 dark:bg-white/10 border border-black/10 dark:border-white/10 rounded-lg text-black/90 dark:text-white placeholder:text-black/40 dark:placeholder:text-white/40 focus:outline-none focus:ring-2 focus:ring-blue-500/30 focus:border-blue-400/50 transition-colors"
+          @input="handleSearchInput"
+        />
+      </div>
+    </div>
+  @endif
+</div>

package/src/ui/sidebar/SidebarItem.stx

@@ -0,0 +1,118 @@
+<script>
+/**
+ * SidebarItem Component
+ *
+ * An individual navigation item within a sidebar section.
+ * Supports icons, badges, active states, and keyboard navigation.
+ *
+ * @example
+ * <SidebarItem
+ *   id="home"
+ *   label="Home"
+ *   icon="i-hugeicons-home-02"
+ *   href="/"
+ *   :active="true"
+ * />
+ */
+
+// Props
+export const id = $props.id || ''
+export const label = $props.label || ''
+export const icon = $props.icon || ''
+export const href = $props.href || ''
+export const badge = $props.badge || ''
+export const active = $props.active ?? false
+export const disabled = $props.disabled ?? false
+export const indent = $props.indent ?? false
+export const onClick = $props.onClick
+
+// Handle click
+function handleClick(event) {
+  if (disabled) {
+    event.preventDefault()
+    return
+  }
+
+  if (onClick) {
+    onClick(event)
+  }
+}
+
+// Build item classes - macOS Tahoe style with translucent-friendly colors
+function getItemClasses() {
+  const baseClasses = [
+    'flex items-center gap-2.5 px-2.5 py-1.5 rounded-md text-[13px]',
+    'transition-all duration-150',
+    indent ? 'ml-2' : ''
+  ]
+
+  if (disabled) {
+    baseClasses.push('opacity-50 cursor-not-allowed')
+  } else if (active) {
+    // Active state - subtle blue highlight like macOS
+    baseClasses.push(
+      'bg-blue-500/20 text-blue-600 dark:bg-blue-400/25 dark:text-blue-300 font-medium'
+    )
+  } else {
+    // Default state - works with translucent backgrounds
+    baseClasses.push(
+      'text-black/80 dark:text-white/80',
+      'hover:bg-black/5 dark:hover:bg-white/10'
+    )
+  }
+
+  return baseClasses.filter(Boolean).join(' ')
+}
+
+// Icon classes
+function getIconClasses() {
+  const baseClasses = 'w-4 h-4 flex-shrink-0'
+
+  if (active) {
+    return `${icon} ${baseClasses} text-blue-600 dark:text-blue-300`
+  }
+
+  return `${icon} ${baseClasses} text-black/50 dark:text-white/50`
+}
+</script>
+
+@if(href && !disabled)
+  <a
+    href="{{ href }}"
+    class="{{ getItemClasses() }}"
+    @click="handleClick"
+    @if(active)
+      aria-current="page"
+    @endif
+  >
+    @if(icon)
+      <div class="{{ getIconClasses() }}"></div>
+    @endif
+    <span class="flex-1 truncate">{{ label }}</span>
+    @if(badge)
+      <span class="ml-auto px-2 py-0.5 text-xs font-medium rounded-full bg-black/10 text-black/70 dark:bg-white/15 dark:text-white/70">
+        {{ badge }}
+      </span>
+    @endif
+  </a>
+@else
+  <button
+    type="button"
+    class="{{ getItemClasses() }}"
+    @click="handleClick"
+    @if(disabled)
+      disabled
+      aria-disabled="true"
+    @endif
+  >
+    @if(icon)
+      <div class="{{ getIconClasses() }}"></div>
+    @endif
+    <span class="flex-1 truncate text-left">{{ label }}</span>
+    @if(badge)
+      <span class="ml-auto px-2 py-0.5 text-xs font-medium rounded-full bg-black/10 text-black/70 dark:bg-white/15 dark:text-white/70">
+        {{ badge }}
+      </span>
+    @endif
+  </button>
+@endif

package/src/ui/sidebar/SidebarSection.stx

@@ -0,0 +1,108 @@
+<script>
+/**
+ * SidebarSection Component
+ *
+ * A collapsible section within the sidebar containing navigation items.
+ * Follows macOS Finder sidebar conventions.
+ *
+ * @example
+ * <SidebarSection
+ *   id="favorites"
+ *   label="Favorites"
+ *   icon="i-hugeicons-star"
+ *   :items="favoriteItems"
+ *   :expanded="true"
+ * />
+ */
+
+// Props
+export const id = $props.id || ''
+export const label = $props.label || ''
+export const icon = $props.icon || ''
+export const items = $props.items || []
+export const expanded = $props.expanded ?? true
+export const collapsible = $props.collapsible ?? true
+export const showLabel = $props.showLabel ?? true
+export const onToggle = $props.onToggle
+export const onItemClick = $props.onItemClick
+
+// Handle section header click
+function handleHeaderClick() {
+  if (collapsible && onToggle) {
+    onToggle(id)
+  }
+}
+
+// Handle item click
+function handleItemClick(item, event) {
+  if (onItemClick) {
+    onItemClick(item, event)
+  }
+}
+
+// Section header classes - macOS Finder style
+const headerClasses = [
+  'w-full flex items-center gap-2.5 px-2.5 py-1.5 rounded-md text-left',
+  'transition-all duration-150',
+  'text-black/60 dark:text-white/60',
+  collapsible ? 'hover:bg-black/5 dark:hover:bg-white/10 cursor-pointer' : ''
+].filter(Boolean).join(' ')
+</script>
+
+<div class="py-1">
+  <!-- Section header -->
+  @if(collapsible)
+    <button
+      type="button"
+      class="{{ headerClasses }}"
+      @click="handleHeaderClick"
+      aria-expanded="{{ expanded }}"
+      aria-controls="sidebar-section-{{ id }}"
+    >
+      @if(icon)
+        <div class="{{ icon }} w-4 h-4 flex-shrink-0 opacity-70"></div>
+      @endif
+      @if(showLabel)
+        <span class="flex-1 text-[13px] font-semibold tracking-tight truncate">
+          {{ label }}
+        </span>
+        <div class="i-hugeicons-arrow-right-01 w-3 h-3 transition-transform duration-200 opacity-50 {{ expanded ? 'rotate-90' : '' }}"></div>
+      @endif
+    </button>
+  @else
+    <div class="{{ headerClasses }}">
+      @if(icon)
+        <div class="{{ icon }} w-4 h-4 flex-shrink-0 opacity-70"></div>
+      @endif
+      @if(showLabel)
+        <span class="flex-1 text-[13px] font-semibold tracking-tight truncate">
+          {{ label }}
+        </span>
+      @endif
+    </div>
+  @endif
+
+  <!-- Section items -->
+  @if(expanded && showLabel && items.length > 0)
+    <div
+      id="sidebar-section-{{ id }}"
+      class="mt-1 space-y-0.5 overflow-hidden"
+      role="group"
+      aria-label="{{ label }}"
+    >
+      @foreach(items as item)
+        <SidebarItem
+          :id="item.id"
+          :label="item.label"
+          :icon="item.icon"
+          :href="item.href"
+          :badge="item.badge"
+          :active="item.active"
+          :disabled="item.disabled"
+          :indent="true"
+          @click="handleItemClick(item, $event)"
+        />
+      @endforeach
+    </div>
+  @endif
+</div>

package/src/ui/sidebar/index.ts

@@ -0,0 +1,175 @@
+export { default as Sidebar } from './Sidebar.stx'
+export { default as SidebarSection } from './SidebarSection.stx'
+export { default as SidebarItem } from './SidebarItem.stx'
+export { default as SidebarHeader } from './SidebarHeader.stx'
+export { default as SidebarFooter } from './SidebarFooter.stx'
+
+// Types
+export interface SidebarItemData {
+  id: string
+  label: string
+  icon?: string
+  href?: string
+  badge?: string | number
+  active?: boolean
+  disabled?: boolean
+}
+
+export interface SidebarSectionData {
+  id: string
+  label: string
+  icon?: string
+  items: SidebarItemData[]
+  expanded?: boolean
+  collapsible?: boolean
+}
+
+export interface SidebarProps {
+  /** Array of sidebar sections with their items */
+  sections?: SidebarSectionData[]
+  /** Whether the sidebar is collapsed */
+  collapsed?: boolean
+  /** Whether the sidebar can be collapsed */
+  collapsible?: boolean
+  /** Width of the expanded sidebar in pixels */
+  width?: number
+  /** Minimum width when collapsed in pixels */
+  minWidth?: number
+  /** Visual style variant */
+  variant?: 'tahoe' | 'vibrancy' | 'solid' | 'transparent'
+  /** Position of the sidebar */
+  position?: 'left' | 'right'
+  /** Whether to show border */
+  bordered?: boolean
+  /** Additional CSS classes */
+  className?: string
+  /** Callback when collapse state changes */
+  onCollapse?: (collapsed: boolean) => void
+  /** Callback when a section is toggled */
+  onSectionToggle?: (sectionId: string) => void
+  /** Callback when an item is clicked */
+  onItemClick?: (item: SidebarItemData, event: Event) => void
+}
+
+export interface SidebarSectionProps {
+  id: string
+  label: string
+  icon?: string
+  items: SidebarItemData[]
+  expanded?: boolean
+  collapsible?: boolean
+  showLabel?: boolean
+  onToggle?: (id: string) => void
+  onItemClick?: (item: SidebarItemData, event: Event) => void
+}
+
+export interface SidebarItemProps {
+  id: string
+  label: string
+  icon?: string
+  href?: string
+  badge?: string | number
+  active?: boolean
+  disabled?: boolean
+  indent?: boolean
+  onClick?: (event: Event) => void
+}
+
+export interface SidebarHeaderProps {
+  title?: string
+  subtitle?: string
+  logo?: string
+  logoIcon?: string
+  showSearch?: boolean
+  searchPlaceholder?: string
+  searchValue?: string
+  collapsed?: boolean
+  onSearch?: (value: string) => void
+}
+
+export interface SidebarFooterProps {
+  showSettings?: boolean
+  showThemeToggle?: boolean
+  settingsHref?: string
+  settingsLabel?: string
+  collapsed?: boolean
+  actions?: Array<{
+    label: string
+    icon?: string
+    href?: string
+    onClick?: () => void
+  }>
+  onThemeToggle?: () => void
+}
+
+/**
+ * Native Sidebar Configuration
+ *
+ * Used to configure the native macOS sidebar when running with Craft's --native-sidebar flag.
+ * The sidebar uses NSOutlineView with vibrancy for a true Tahoe-style appearance.
+ */
+export interface NativeSidebarConfig {
+  /** Header configuration */
+  header?: {
+    title?: string
+    subtitle?: string
+    icon?: string // SF Symbol name (e.g., 'house.fill', 'message.fill')
+  }
+  /** Search placeholder text */
+  searchPlaceholder?: string
+  /** Array of sidebar sections */
+  sections: NativeSidebarSection[]
+  /** Minimum width when collapsed */
+  minWidth?: number
+  /** Maximum width */
+  maxWidth?: number
+  /** Whether the sidebar can be collapsed */
+  canCollapse?: boolean
+}
+
+export interface NativeSidebarSection {
+  /** Unique section ID */
+  id: string
+  /** Section title (shown as header) */
+  title: string
+  /** Whether section is collapsible */
+  collapsible?: boolean
+  /** Whether section starts collapsed */
+  collapsed?: boolean
+  /** Items in this section */
+  items: NativeSidebarItem[]
+}
+
+export interface NativeSidebarItem {
+  /** Unique item ID */
+  id: string
+  /** Display label */
+  label: string
+  /** SF Symbol icon name (e.g., 'tray.fill', 'envelope.badge.fill') */
+  icon?: string
+  /** Badge count or text */
+  badge?: string | number
+  /** Tint color for the icon (hex) */
+  tintColor?: string
+  /** Whether this item is selected */
+  selected?: boolean
+  /** Whether this item is disabled */
+  disabled?: boolean
+  /** Nested children items */
+  children?: NativeSidebarItem[]
+  /** Custom data to pass to selection handler */
+  data?: Record<string, unknown>
+}
+
+/**
+ * Craft sidebar selection event
+ * Passed to window.craft._sidebarSelectHandler when user clicks a sidebar item
+ */
+export interface SidebarSelectEvent {
+  /** ID of the selected item */
+  itemId: string
+  /** The full item object */
+  item: NativeSidebarItem
+  /** Parent section ID */
+  sectionId?: string
+}

package/src/ui/skeleton/Skeleton.stx

@@ -0,0 +1,48 @@
+<script>
+export const variant = $props.variant || 'text'
+export const count = $props.count || 1
+export const width = $props.width || ''
+export const height = $props.height || ''
+export const circle = $props.circle || false
+export const className = $props.className || ''
+export const animate = $props.animate ?? true
+
+// Variant classes
+const variantClasses = {
+  text: 'h-4 rounded',
+  title: 'h-8 rounded',
+  avatar: 'w-10 h-10 rounded-full',
+  thumbnail: 'w-24 h-24 rounded-md',
+  button: 'h-10 w-32 rounded-md',
+  card: 'h-64 rounded-lg',
+  rect: 'rounded-md',
+}
+
+// Animation classes
+const animationClasses = animate ? 'animate-pulse' : ''
+
+// Build base classes
+const baseClasses = circle ? 'rounded-full' : variantClasses[variant]
+
+// Build style object
+let styleString = ''
+if (width) {
+  styleString += `width: ${typeof width === 'number' ? width + 'px' : width};`
+}
+if (height) {
+  styleString += `height: ${typeof height === 'number' ? height + 'px' : height};`
+}
+
+export const skeletonClasses = `bg-gray-200 dark:bg-gray-700 ${baseClasses} ${animationClasses} ${className}`.trim()
+export const containerClasses = count > 1 ? 'space-y-3' : ''
+</script>
+
+@if(count > 1)
+  <div class="{{ containerClasses }}">
+    @for(i = 0; i < count; i++)
+      <div class="{{ skeletonClasses }}" style="{{ styleString }}" aria-busy="true" aria-live="polite"></div>
+    @endfor
+  </div>
+@else
+  <div class="{{ skeletonClasses }}" style="{{ styleString }}" aria-busy="true" aria-live="polite"></div>
+@endif

package/src/ui/skeleton/index.ts

@@ -0,0 +1,11 @@
+export { default as Skeleton } from './Skeleton.stx'
+
+export interface SkeletonProps {
+  variant?: 'text' | 'title' | 'avatar' | 'thumbnail' | 'button' | 'card' | 'rect'
+  count?: number
+  width?: string | number
+  height?: string | number
+  circle?: boolean
+  animate?: boolean
+  className?: string
+}

package/src/ui/spinner/Spinner.stx

@@ -0,0 +1,109 @@
+<script>
+export const variant = $props.variant || 'circle'
+export const size = $props.size || 'md'
+export const color = $props.color || 'primary'
+export const label = $props.label || ''
+export const className = $props.className || ''
+
+// Size classes
+const sizeClasses = {
+  xs: 'w-3 h-3',
+  sm: 'w-4 h-4',
+  md: 'w-6 h-6',
+  lg: 'w-8 h-8',
+  xl: 'w-12 h-12',
+}
+
+// Color classes
+const colorClasses = {
+  primary: 'text-blue-600 dark:text-blue-500',
+  secondary: 'text-purple-600 dark:text-purple-500',
+  success: 'text-green-600 dark:text-green-500',
+  warning: 'text-yellow-600 dark:text-yellow-500',
+  danger: 'text-red-600 dark:text-red-500',
+  info: 'text-cyan-600 dark:text-cyan-500',
+  white: 'text-white',
+  gray: 'text-gray-600 dark:text-gray-400',
+}
+
+export const containerClasses = `inline-flex flex-col items-center gap-2 ${className}`.trim()
+export const spinnerClasses = `${sizeClasses[size]} ${colorClasses[color]} animate-spin`.trim()
+export const labelClasses = `text-sm font-medium text-gray-700 dark:text-gray-300`.trim()
+
+// Dots size classes
+const dotsSizeClasses = {
+  xs: 'w-1 h-1',
+  sm: 'w-1.5 h-1.5',
+  md: 'w-2 h-2',
+  lg: 'w-2.5 h-2.5',
+  xl: 'w-3 h-3',
+}
+
+const dotsColorClasses = {
+  primary: 'bg-blue-600 dark:bg-blue-500',
+  secondary: 'bg-purple-600 dark:bg-purple-500',
+  success: 'bg-green-600 dark:bg-green-500',
+  warning: 'bg-yellow-600 dark:bg-yellow-500',
+  danger: 'bg-red-600 dark:bg-red-500',
+  info: 'bg-cyan-600 dark:bg-cyan-500',
+  white: 'bg-white',
+  gray: 'bg-gray-600 dark:bg-gray-400',
+}
+
+export const dotClasses = `${dotsSizeClasses[size]} ${dotsColorClasses[color]} rounded-full`.trim()
+</script>
+
+<div class="{{ containerClasses }}" role="status" aria-live="polite" aria-busy="true">
+  @if(variant === 'circle')
+    <!-- Circle spinner (default) -->
+    <svg class="{{ spinnerClasses }}" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+      <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+      <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+    </svg>
+  @elseif(variant === 'dots')
+    <!-- Dots spinner -->
+    <div class="flex items-center gap-1">
+      <div class="{{ dotClasses }}" style="animation: bounce 1.4s infinite ease-in-out both; animation-delay: -0.32s"></div>
+      <div class="{{ dotClasses }}" style="animation: bounce 1.4s infinite ease-in-out both; animation-delay: -0.16s"></div>
+      <div class="{{ dotClasses }}" style="animation: bounce 1.4s infinite ease-in-out both"></div>
+    </div>
+  @elseif(variant === 'bars')
+    <!-- Bars spinner -->
+    <div class="flex items-center gap-1">
+      <div class="w-1 bg-current rounded-full" style="height: {{ size === 'xs' ? '8px' : size === 'sm' ? '12px' : size === 'md' ? '16px' : size === 'lg' ? '20px' : '24px' }}; animation: bars 1.2s infinite ease-in-out; animation-delay: -0.24s"></div>
+      <div class="w-1 bg-current rounded-full" style="height: {{ size === 'xs' ? '8px' : size === 'sm' ? '12px' : size === 'md' ? '16px' : size === 'lg' ? '20px' : '24px' }}; animation: bars 1.2s infinite ease-in-out; animation-delay: -0.12s"></div>
+      <div class="w-1 bg-current rounded-full" style="height: {{ size === 'xs' ? '8px' : size === 'sm' ? '12px' : size === 'md' ? '16px' : size === 'lg' ? '20px' : '24px' }}; animation: bars 1.2s infinite ease-in-out"></div>
+    </div>
+  @elseif(variant === 'ring')
+    <!-- Ring spinner -->
+    <div class="{{ spinnerClasses }}" style="border: 2px solid currentColor; border-top-color: transparent; border-radius: 50%;"></div>
+  @endif
+
+  @if(label)
+    <span class="{{ labelClasses }}">{{ label }}</span>
+  @endif
+
+  <span class="sr-only">{{ label || 'Loading...' }}</span>
+</div>
+
+<style>
+@keyframes bounce {
+  0%, 80%, 100% {
+    transform: scale(0);
+    opacity: 0.5;
+  }
+  40% {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+
+@keyframes bars {
+  0%, 40%, 100% {
+    transform: scaleY(0.4);
+  }
+  20% {
+    transform: scaleY(1);
+  }
+}
+</style>

package/src/ui/spinner/index.ts

@@ -0,0 +1,9 @@
+export { default as Spinner } from './Spinner.stx'
+
+export interface SpinnerProps {
+  variant?: 'circle' | 'dots' | 'bars' | 'ring'
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info' | 'white' | 'gray'
+  label?: string
+  className?: string
+}