@stacksjs/components 0.2.3

package/src/ui/select/README.md

@@ -0,0 +1,204 @@
+# Select Component
+
+A styled native select dropdown with support for labels, validation, and dark mode.
+
+## Installation
+
+```bash
+bun add @stacksjs/components
+```
+
+## Usage
+
+### Basic Select
+
+```stx
+<script>
+export const options = [
+  { value: 'option1', label: 'Option 1' },
+  { value: 'option2', label: 'Option 2' },
+  { value: 'option3', label: 'Option 3' },
+]
+
+export const selected = 'option1'
+
+export const handleChange = (value) => {
+  console.log('Selected:', value)
+  selected = value
+}
+</script>
+
+@component('Select', {
+  value: selected,
+  onChange: handleChange,
+  options: options,
+  placeholder: 'Choose an option'
+})
+@endcomponent
+```
+
+### With Label and Helper Text
+
+```stx
+@component('Select', {
+  label: 'Country',
+  helperText: 'Select your country of residence',
+  value: country,
+  onChange: (val) => country = val,
+  options: countries,
+  required: true
+})
+@endcomponent
+```
+
+### With Error State
+
+```stx
+@component('Select', {
+  label: 'Category',
+  value: category,
+  onChange: (val) => category = val,
+  options: categories,
+  error: true,
+  helperText: 'Please select a valid category',
+  required: true
+})
+@endcomponent
+```
+
+### Different Sizes
+
+```stx
+<!-- Small -->
+@component('Select', {
+  size: 'sm',
+  options: options
+})
+@endcomponent
+
+<!-- Medium (default) -->
+@component('Select', {
+  size: 'md',
+  options: options
+})
+@endcomponent
+
+<!-- Large -->
+@component('Select', {
+  size: 'lg',
+  options: options
+})
+@endcomponent
+```
+
+### Disabled State
+
+```stx
+@component('Select', {
+  disabled: true,
+  value: 'locked',
+  options: options
+})
+@endcomponent
+```
+
+### With Disabled Options
+
+```stx
+<script>
+export const options = [
+  { value: '1', label: 'Available Option' },
+  { value: '2', label: 'Disabled Option', disabled: true },
+  { value: '3', label: 'Another Available' },
+]
+</script>
+
+@component('Select', {
+  options: options
+})
+@endcomponent
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| number` | `''` | Selected value |
+| `onChange` | `function` | - | Callback when selection changes |
+| `options` | `SelectOption[]` | `[]` | Array of options |
+| `placeholder` | `string` | `'Select an option'` | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable the select |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Select size |
+| `error` | `boolean` | `false` | Show error state |
+| `label` | `string` | `''` | Label text |
+| `helperText` | `string` | `''` | Helper/error text below select |
+| `required` | `boolean` | `false` | Mark as required |
+| `className` | `string` | `''` | Additional CSS classes |
+
+## SelectOption Interface
+
+```typescript
+interface SelectOption {
+  value: string | number
+  label: string
+  disabled?: boolean
+}
+```
+
+## Features
+
+- **Native select** - Uses native `<select>` element for best UX
+- **3 sizes** - Small, medium, and large
+- **Dark mode** - Full dark mode support
+- **Validation states** - Error and required states
+- **Disabled options** - Individual options can be disabled
+- **Labels and helpers** - Support for labels and helper text
+- **Accessible** - Proper ARIA attributes and labels
+- **Keyboard navigation** - Full keyboard support
+- **Modern ES modules** - Clean export syntax
+- **Headwind styling** - Utility-first CSS classes
+
+## Accessibility
+
+- Proper `label` associations with `for` attribute
+- `aria-invalid` for error states
+- `aria-describedby` for helper text
+- Required field indicator
+- Disabled state properly communicated
+- Keyboard navigable
+
+## Example: Form Select
+
+```stx
+<script>
+export const countries = [
+  { value: 'us', label: 'United States' },
+  { value: 'ca', label: 'Canada' },
+  { value: 'mx', label: 'Mexico' },
+  { value: 'uk', label: 'United Kingdom' },
+  { value: 'de', label: 'Germany' },
+]
+
+export let selectedCountry = ''
+export let hasError = false
+
+export const handleCountryChange = (value) => {
+  selectedCountry = value
+  hasError = !value
+}
+</script>
+
+<form>
+  @component('Select', {
+    label: 'Country',
+    value: selectedCountry,
+    onChange: handleCountryChange,
+    options: countries,
+    placeholder: 'Select your country',
+    required: true,
+    error: hasError,
+    helperText: hasError ? 'Country is required' : 'Choose your country'
+  })
+  @endcomponent
+</form>
+```

package/src/ui/select/Select.stx

@@ -0,0 +1,89 @@
+<script>
+export const value = $props.value || ''
+export const onChange = $props.onChange || (() => {})
+export const options = $props.options || []
+export const placeholder = $props.placeholder || 'Select an option'
+export const disabled = $props.disabled || false
+export const size = $props.size || 'md'
+export const error = $props.error || false
+export const label = $props.label || ''
+export const helperText = $props.helperText || ''
+export const required = $props.required || false
+export const className = $props.className || ''
+
+// Size classes
+const sizeClasses = {
+  sm: 'px-3 py-1.5 text-sm h-8',
+  md: 'px-4 py-2 text-base h-10',
+  lg: 'px-5 py-3 text-lg h-12',
+}
+
+// Base and state classes
+const baseClasses = 'block w-full border-0 rounded-md shadow-sm ring-1 ring-inset transition-colors duration-200 focus:ring-2 focus:ring-inset dark:bg-blue-gray-700 dark:text-gray-100'
+
+const stateClasses = error
+  ? 'ring-red-300 dark:ring-red-600 text-red-900 dark:text-red-300 placeholder-red-300 dark:placeholder-red-500 focus:ring-red-500 dark:focus:ring-red-400'
+  : 'ring-gray-300 dark:ring-gray-600 text-gray-900 dark:text-gray-100 placeholder-gray-400 dark:placeholder-gray-500 focus:ring-indigo-600 dark:focus:ring-indigo-400'
+
+const disabledClasses = disabled
+  ? 'opacity-50 cursor-not-allowed bg-gray-50 dark:bg-gray-800'
+  : 'bg-white dark:bg-blue-gray-700 cursor-pointer hover:ring-gray-400 dark:hover:ring-gray-500'
+
+export const selectClasses = `${baseClasses} ${sizeClasses[size]} ${stateClasses} ${disabledClasses} ${className}`.trim()
+export const labelClasses = `block text-sm font-medium leading-6 ${error ? 'text-red-600 dark:text-red-400' : 'text-gray-900 dark:text-gray-100'}`.trim()
+export const helperClasses = `mt-2 text-sm ${error ? 'text-red-600 dark:text-red-400' : 'text-gray-500 dark:text-gray-400'}`.trim()
+</script>
+
+<div class="w-full">
+  @if(label)
+    <label for="select-{{ value }}" class="{{ labelClasses }}">
+      {{ label }}
+      @if(required)
+        <span class="text-red-500 ml-1">*</span>
+      @endif
+    </label>
+  @endif
+
+  <div class="{{ label ? 'mt-2' : '' }}">
+    <select
+      id="select-{{ value }}"
+      class="{{ selectClasses }}"
+      value="{{ value }}"
+      disabled="{{ disabled }}"
+      required="{{ required }}"
+      onchange="handleChange(event)"
+      aria-invalid="{{ error ? 'true' : 'false' }}"
+      aria-describedby="{{ helperText ? 'helper-text' : '' }}"
+    >
+      @if(placeholder)
+        <option value="" disabled selected>{{ placeholder }}</option>
+      @endif
+
+      @foreach(option in options)
+        <option
+          value="{{ option.value }}"
+          selected="{{ option.value === value }}"
+          disabled="{{ option.disabled }}"
+        >
+          {{ option.label }}
+        </option>
+      @endforeach
+    </select>
+  </div>
+
+  @if(helperText)
+    <p id="helper-text" class="{{ helperClasses }}">
+      {{ helperText }}
+    </p>
+  @endif
+</div>
+
+<script>
+function handleChange(event) {
+  const newValue = event.target.value
+
+  if (onChange) {
+    onChange(newValue)
+  }
+}
+</script>

package/src/ui/select/index.ts

@@ -0,0 +1,21 @@
+export { default as Select } from './Select.stx'
+
+export interface SelectOption {
+  value: string | number
+  label: string
+  disabled?: boolean
+}
+
+export interface SelectProps {
+  value?: string | number
+  onChange?: (value: string | number) => void
+  options?: SelectOption[]
+  placeholder?: string
+  disabled?: boolean
+  size?: 'sm' | 'md' | 'lg'
+  error?: boolean
+  label?: string
+  helperText?: string
+  required?: boolean
+  className?: string
+}

package/src/ui/sidebar/Sidebar.stx

@@ -0,0 +1,288 @@
+<script>
+/**
+ * Sidebar Component - macOS Native Style
+ *
+ * A native-feeling sidebar component that integrates with Craft for true native rendering
+ * when running in a Craft desktop environment, with beautiful macOS Tahoe-style fallback
+ * for web environments.
+ *
+ * @example
+ * <Sidebar
+ *   :sections="sections"
+ *   :collapsed="false"
+ *   :width="240"
+ *   variant="tahoe"
+ * >
+ *   <template #header>
+ *     <SidebarHeader title="My App" />
+ *   </template>
+ *   <template #footer>
+ *     <SidebarFooter />
+ *   </template>
+ * </Sidebar>
+ */
+
+// Props
+export const sections = $props.sections || []
+export const collapsed = $props.collapsed ?? false
+export const collapsible = $props.collapsible ?? true
+export const width = $props.width || 240
+export const minWidth = $props.minWidth || 64
+export const variant = $props.variant || 'tahoe' // 'tahoe' | 'vibrancy' | 'solid' | 'transparent'
+export const position = $props.position || 'left' // 'left' | 'right'
+export const bordered = $props.bordered ?? true
+export const className = $props.className || ''
+export const onCollapse = $props.onCollapse
+export const onSectionToggle = $props.onSectionToggle
+export const onItemClick = $props.onItemClick
+
+// Internal state
+let isHovered = false
+let nativeSidebarId = null
+
+// Check if running in Craft environment with native sidebar enabled
+// When Craft uses --native-sidebar, it sets these flags and we should NOT render the web sidebar
+const hasNativeSidebar = typeof window !== 'undefined' && (
+  window.__craftNativeSidebar === true ||
+  window.craft?.hasNativeSidebar?.() ||
+  (window.webkit?.messageHandlers?.craft && document.body?.dataset?.nativeSidebar === 'true')
+)
+
+// Check if running in Craft environment (may not have native sidebar)
+const isCraft = typeof window !== 'undefined' && window.craft?.isCraft?.()
+
+// Variant styles - macOS Tahoe inspired
+// Native macOS sidebars use vibrancy where desktop background shines through
+const variantStyles = {
+  tahoe: {
+    // Translucent with warm tint overlay - desktop shows through
+    bg: 'bg-white/70 dark:bg-black/50',
+    border: 'border-black/5 dark:border-white/10',
+    backdrop: 'backdrop-blur-2xl backdrop-saturate-180',
+    // Warm tint is applied via pseudo-element in template
+    tint: true
+  },
+  vibrancy: {
+    bg: 'bg-white/50 dark:bg-black/40',
+    border: 'border-white/20 dark:border-white/10',
+    backdrop: 'backdrop-blur-3xl backdrop-saturate-200',
+    tint: false
+  },
+  solid: {
+    bg: 'bg-stone-100 dark:bg-neutral-900',
+    border: 'border-stone-200 dark:border-neutral-800',
+    backdrop: '',
+    tint: false
+  },
+  transparent: {
+    bg: 'bg-transparent',
+    border: 'border-transparent',
+    backdrop: '',
+    tint: false
+  }
+}
+
+// Get current variant style
+function getVariantStyle() {
+  return variantStyles[variant] || variantStyles.tahoe
+}
+
+// Calculate sidebar width
+function getSidebarWidth() {
+  if (collapsed && !isHovered) {
+    return `${minWidth}px`
+  }
+  return `${width}px`
+}
+
+// Check if showing expanded content
+function showExpanded() {
+  return !collapsed || isHovered
+}
+
+// Initialize Craft native sidebar if available
+async function initNativeSidebar() {
+  if (isCraft && window.craft?.components?.createSidebar) {
+    try {
+      const config = {
+        position,
+        width,
+        minWidth,
+        collapsible,
+        sections: sections.map(section => ({
+          id: section.id,
+          label: section.label,
+          items: section.items?.map(item => ({
+            id: item.id,
+            label: item.label,
+            icon: item.icon,
+            href: item.href,
+            badge: item.badge
+          }))
+        }))
+      }
+      nativeSidebarId = await window.craft.components.createSidebar(config)
+    } catch (err) {
+      console.warn('[Sidebar] Failed to create native sidebar, using web fallback:', err)
+    }
+  }
+}
+
+// Handle collapse toggle
+function handleCollapseToggle() {
+  if (onCollapse) {
+    onCollapse(!collapsed)
+  }
+}
+
+// Handle mouse enter/leave for hover expand
+function handleMouseEnter() {
+  if (collapsed && collapsible) {
+    isHovered = true
+  }
+}
+
+function handleMouseLeave() {
+  isHovered = false
+}
+
+// Handle section toggle
+function handleSectionToggle(sectionId) {
+  if (onSectionToggle) {
+    onSectionToggle(sectionId)
+  }
+}
+
+// Handle item click
+function handleItemClick(item, event) {
+  if (onItemClick) {
+    onItemClick(item, event)
+  }
+}
+
+// Build container classes
+const style = getVariantStyle()
+
+// Build border classes properly for Tailwind
+function getBorderClasses() {
+  if (!bordered) return ''
+  const borderSide = position === 'left' ? 'border-r' : 'border-l'
+  return `${borderSide} ${style.border}`
+}
+
+const containerClasses = [
+  'fixed inset-y-0 z-50 flex flex-col',
+  'transition-all duration-300 ease-out',
+  'overflow-hidden', // Contain the tint overlay
+  style.bg,
+  style.backdrop,
+  getBorderClasses(),
+  position === 'left' ? 'left-0' : 'right-0',
+  className
+].filter(Boolean).join(' ')
+
+// Initialize native sidebar on mount
+if (typeof window !== 'undefined') {
+  initNativeSidebar()
+}
+</script>
+
+<!-- Only render web sidebar when NOT running in Craft native sidebar mode -->
+@if(!hasNativeSidebar)
+<aside
+  class="{{ containerClasses }} sidebar-container"
+  style="width: {{ getSidebarWidth() }}"
+  @mouseenter="handleMouseEnter"
+  @mouseleave="handleMouseLeave"
+  role="navigation"
+  aria-label="Sidebar navigation"
+>
+  <!-- Warm tint overlay for macOS Tahoe effect - desktop shows through -->
+  @if(style.tint)
+    <div class="absolute inset-0 pointer-events-none bg-gradient-to-b from-amber-50/30 via-orange-50/20 to-stone-100/30 dark:from-neutral-800/20 dark:via-neutral-900/10 dark:to-neutral-800/20 mix-blend-overlay"></div>
+  @endif
+
+  <!-- Header slot -->
+  @if($slots.header)
+    <div class="flex-shrink-0 relative z-10">
+      <slot name="header" />
+    </div>
+  @endif
+
+  <!-- Main content area with sections -->
+  <div class="flex-1 overflow-y-auto overflow-x-hidden relative z-10">
+    @if(sections.length > 0)
+      <nav class="px-3 py-2 space-y-1">
+        @foreach(sections as section)
+          <SidebarSection
+            :id="section.id"
+            :label="section.label"
+            :icon="section.icon"
+            :items="section.items"
+            :expanded="section.expanded !== false"
+            :collapsible="section.collapsible !== false"
+            :showLabel="showExpanded()"
+            @toggle="handleSectionToggle(section.id)"
+            @itemClick="handleItemClick"
+          />
+        @endforeach
+      </nav>
+    @else
+      <!-- Default slot for custom content -->
+      <div class="px-3 py-2">
+        <slot />
+      </div>
+    @endif
+  </div>
+
+  <!-- Footer slot -->
+  @if($slots.footer)
+    <div class="flex-shrink-0 relative z-10">
+      <slot name="footer" />
+    </div>
+  @endif
+
+  <!-- Collapse toggle button -->
+  @if(collapsible && showExpanded())
+    <button
+      type="button"
+      class="absolute top-4 {{ position === 'left' ? 'right-2' : 'left-2' }} p-1.5 rounded-lg text-stone-400 hover:text-stone-600 hover:bg-black/5 dark:hover:text-neutral-300 dark:hover:bg-white/10 transition-colors z-20"
+      @click="handleCollapseToggle"
+      aria-label="{{ collapsed ? 'Expand sidebar' : 'Collapse sidebar' }}"
+    >
+      <div class="{{ collapsed ? 'i-hugeicons-sidebar-right' : 'i-hugeicons-sidebar-left' }} w-5 h-5"></div>
+    </button>
+  @endif
+</aside>
+@endif
+
+<style scoped>
+/* Smooth scrollbar styling for macOS feel */
+.overflow-y-auto::-webkit-scrollbar {
+  width: 6px;
+}
+
+.overflow-y-auto::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.overflow-y-auto::-webkit-scrollbar-thumb {
+  background-color: rgba(0, 0, 0, 0.15);
+  border-radius: 3px;
+}
+
+.overflow-y-auto::-webkit-scrollbar-thumb:hover {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* Dark mode scrollbar */
+@media (prefers-color-scheme: dark) {
+  .overflow-y-auto::-webkit-scrollbar-thumb {
+    background-color: rgba(255, 255, 255, 0.15);
+  }
+
+  .overflow-y-auto::-webkit-scrollbar-thumb:hover {
+    background-color: rgba(255, 255, 255, 0.25);
+  }
+}
+</style>

package/src/ui/sidebar/SidebarFooter.stx

@@ -0,0 +1,95 @@
+<script>
+/**
+ * SidebarFooter Component
+ *
+ * A footer component for the sidebar with quick actions and settings.
+ *
+ * @example
+ * <SidebarFooter
+ *   :showSettings="true"
+ *   :showThemeToggle="true"
+ *   settingsHref="/settings"
+ * />
+ */
+
+// Props
+export const showSettings = $props.showSettings ?? true
+export const showThemeToggle = $props.showThemeToggle ?? true
+export const settingsHref = $props.settingsHref || '/settings'
+export const settingsLabel = $props.settingsLabel || 'Settings'
+export const collapsed = $props.collapsed ?? false
+export const onThemeToggle = $props.onThemeToggle
+
+// Quick action items
+export const actions = $props.actions || []
+
+// Handle theme toggle
+function handleThemeToggle() {
+  if (onThemeToggle) {
+    onThemeToggle()
+  } else {
+    // Default theme toggle behavior
+    document.documentElement.classList.toggle('dark')
+  }
+}
+</script>
+
+<div class="border-t border-black/5 dark:border-white/10 p-3 space-y-2">
+  <!-- Custom actions slot -->
+  <slot />
+
+  <!-- Quick actions row -->
+  @if(!collapsed && actions.length > 0)
+    <div class="flex items-center gap-2">
+      @foreach(actions as action)
+        @if(action.href)
+          <a
+            href="{{ action.href }}"
+            class="flex-1 flex items-center gap-2 px-3 py-2 rounded-lg text-sm text-black/70 dark:text-white/70 hover:bg-black/5 dark:hover:bg-white/10 transition-colors"
+          >
+            @if(action.icon)
+              <div class="{{ action.icon }} w-4 h-4"></div>
+            @endif
+            <span>{{ action.label }}</span>
+          </a>
+        @else
+          <button
+            type="button"
+            class="flex-1 flex items-center gap-2 px-3 py-2 rounded-lg text-sm text-black/70 dark:text-white/70 hover:bg-black/5 dark:hover:bg-white/10 transition-colors"
+            @click="action.onClick"
+          >
+            @if(action.icon)
+              <div class="{{ action.icon }} w-4 h-4"></div>
+            @endif
+            <span>{{ action.label }}</span>
+          </button>
+        @endif
+      @endforeach
+
+      @if(showThemeToggle)
+        <button
+          type="button"
+          class="p-2 rounded-lg text-black/50 hover:text-black/80 hover:bg-black/5 dark:text-white/50 dark:hover:text-white/80 dark:hover:bg-white/10 transition-colors"
+          @click="handleThemeToggle"
+          aria-label="Toggle dark mode"
+        >
+          <div class="i-hugeicons-moon-02 w-4 h-4 dark:hidden"></div>
+          <div class="i-hugeicons-sun-02 w-4 h-4 hidden dark:block"></div>
+        </button>
+      @endif
+    </div>
+  @endif
+
+  <!-- Settings link -->
+  @if(showSettings)
+    <a
+      href="{{ settingsHref }}"
+      class="flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-colors duration-150 text-black/70 dark:text-white/70 hover:bg-black/5 dark:hover:bg-white/10"
+    >
+      <div class="i-hugeicons-settings-02 w-5 h-5 text-black/50 dark:text-white/50"></div>
+      @if(!collapsed)
+        <span>{{ settingsLabel }}</span>
+      @endif
+    </a>
+  @endif
+</div>