@stacksjs/components 0.2.3

package/src/ui/avatar/Avatar.stx

@@ -0,0 +1,88 @@
+<script>
+export const src = $props.src || ''
+export const alt = $props.alt || ''
+export const initials = $props.initials || ''
+export const size = $props.size || 'md'
+export const shape = $props.shape || 'circle'
+export const status = $props.status || ''
+export const className = $props.className || ''
+export const onError = $props.onError
+
+let imageError = false
+
+// Size classes
+const sizeClasses = {
+  xs: 'w-6 h-6 text-xs',
+  sm: 'w-8 h-8 text-sm',
+  md: 'w-10 h-10 text-base',
+  lg: 'w-12 h-12 text-lg',
+  xl: 'w-16 h-16 text-xl',
+  '2xl': 'w-20 h-20 text-2xl',
+}
+
+// Shape classes
+const shapeClasses = {
+  circle: 'rounded-full',
+  square: 'rounded-md',
+}
+
+// Status indicator size classes
+const statusSizeClasses = {
+  xs: 'w-1.5 h-1.5 border',
+  sm: 'w-2 h-2 border',
+  md: 'w-2.5 h-2.5 border-2',
+  lg: 'w-3 h-3 border-2',
+  xl: 'w-3.5 h-3.5 border-2',
+  '2xl': 'w-4 h-4 border-2',
+}
+
+// Status color classes
+const statusColorClasses = {
+  online: 'bg-green-500 dark:bg-green-400',
+  offline: 'bg-gray-400 dark:bg-gray-600',
+  away: 'bg-yellow-500 dark:bg-yellow-400',
+  busy: 'bg-red-500 dark:bg-red-400',
+}
+
+export const containerClasses = `relative inline-block ${className}`.trim()
+export const avatarClasses = `flex items-center justify-center overflow-hidden bg-gray-200 dark:bg-gray-700 ${sizeClasses[size]} ${shapeClasses[shape]}`.trim()
+export const imageClasses = `w-full h-full object-cover`.trim()
+export const initialsClasses = `font-medium text-gray-600 dark:text-gray-300 uppercase select-none`.trim()
+export const statusClasses = `absolute bottom-0 right-0 ${statusSizeClasses[size]} ${statusColorClasses[status]} ${shapeClasses[shape]} border-white dark:border-gray-900`.trim()
+
+// Generate initials from name if not provided
+export const displayInitials = initials || (alt ? alt.split(' ').map(n => n[0]).join('').substring(0, 2) : '?')
+</script>
+
+<div class="{{ containerClasses }}">
+  <div class="{{ avatarClasses }}">
+    @if(src && !imageError)
+      <img
+        src="{{ src }}"
+        alt="{{ alt }}"
+        class="{{ imageClasses }}"
+        onerror="handleImageError(event)"
+      />
+    @else
+      <span class="{{ initialsClasses }}">{{ displayInitials }}</span>
+    @endif
+  </div>
+
+  @if(status)
+    <span
+      class="{{ statusClasses }}"
+      role="status"
+      aria-label="{{ status }}"
+    ></span>
+  @endif
+</div>
+
+<script>
+function handleImageError(event) {
+  imageError = true
+
+  if (onError) {
+    onError(event)
+  }
+}
+</script>

package/src/ui/avatar/index.ts

@@ -0,0 +1,12 @@
+export { default as Avatar } from './Avatar.stx'
+
+export interface AvatarProps {
+  src?: string
+  alt?: string
+  initials?: string
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+  shape?: 'circle' | 'square'
+  status?: 'online' | 'offline' | 'away' | 'busy' | ''
+  onError?: (event: Event) => void
+  className?: string
+}

package/src/ui/badge/Badge.stx

@@ -0,0 +1,70 @@
+<script>
+export const variant = $props.variant || 'default'
+export const size = $props.size || 'md'
+export const dot = $props.dot || false
+export const removable = $props.removable || false
+export const className = $props.className || ''
+export const onRemove = $props.onRemove
+
+// Variant classes
+const variantClasses = {
+  default: 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300',
+  primary: 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200',
+  secondary: 'bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200',
+  success: 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200',
+  warning: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-200',
+  danger: 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200',
+  info: 'bg-cyan-100 text-cyan-800 dark:bg-cyan-900 dark:text-cyan-200',
+}
+
+// Size classes
+const sizeClasses = {
+  sm: 'px-2 py-0.5 text-xs',
+  md: 'px-2.5 py-0.5 text-sm',
+  lg: 'px-3 py-1 text-base',
+}
+
+// Dot color classes
+const dotColorClasses = {
+  default: 'bg-gray-500 dark:bg-gray-400',
+  primary: 'bg-blue-500 dark:bg-blue-400',
+  secondary: 'bg-purple-500 dark:bg-purple-400',
+  success: 'bg-green-500 dark:bg-green-400',
+  warning: 'bg-yellow-500 dark:bg-yellow-400',
+  danger: 'bg-red-500 dark:bg-red-400',
+  info: 'bg-cyan-500 dark:bg-cyan-400',
+}
+
+export const badgeClasses = `inline-flex items-center gap-1.5 font-medium rounded-full ${variantClasses[variant]} ${sizeClasses[size]} ${className}`.trim()
+export const dotClasses = `w-2 h-2 rounded-full ${dotColorClasses[variant]}`.trim()
+export const removeButtonClasses = `ml-0.5 -mr-1 text-current hover:bg-black hover:bg-opacity-10 dark:hover:bg-white dark:hover:bg-opacity-10 rounded-full p-0.5 transition-colors duration-150`.trim()
+</script>
+
+<span class="{{ badgeClasses }}" role="status">
+  @if(dot)
+    <span class="{{ dotClasses }}" aria-hidden="true"></span>
+  @endif
+
+  <slot />
+
+  @if(removable && onRemove)
+    <button
+      type="button"
+      onclick="handleRemove()"
+      class="{{ removeButtonClasses }}"
+      aria-label="Remove"
+    >
+      <svg class="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+      </svg>
+    </button>
+  @endif
+</span>
+
+<script>
+function handleRemove() {
+  if (onRemove) {
+    onRemove()
+  }
+}
+</script>

package/src/ui/badge/index.ts

@@ -0,0 +1,10 @@
+export { default as Badge } from './Badge.stx'
+
+export interface BadgeProps {
+  variant?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'
+  size?: 'sm' | 'md' | 'lg'
+  dot?: boolean
+  removable?: boolean
+  onRemove?: () => void
+  className?: string
+}

package/src/ui/breadcrumb/Breadcrumb.stx

@@ -0,0 +1,79 @@
+<script>
+export const items = $props.items || []
+export const separator = $props.separator || '/'
+export const maxItems = $props.maxItems || 0
+export const className = $props.className || ''
+
+// Handle collapse if maxItems is set
+let displayItems = items
+if (maxItems > 0 && items.length > maxItems) {
+  const firstItems = items.slice(0, 1)
+  const lastItems = items.slice(-(maxItems - 1))
+  displayItems = [...firstItems, { label: '...', href: '#', collapsed: true }, ...lastItems]
+}
+
+// Separator element
+const separatorElement = separator === '/' ? '/' :
+  separator === '>' ? '›' :
+  separator === 'arrow' ? `<svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" /></svg>` :
+  separator
+
+export const breadcrumbClasses = `flex items-center flex-wrap gap-2 text-sm ${className}`.trim()
+export const itemClasses = `text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200 transition-colors duration-150`.trim()
+export const activeItemClasses = `text-gray-900 dark:text-gray-100 font-medium`.trim()
+export const separatorClasses = `text-gray-400 dark:text-gray-600 select-none`.trim()
+export const collapsedClasses = `text-gray-400 dark:text-gray-600 cursor-default`.trim()
+</script>
+
+<nav class="{{ breadcrumbClasses }}" aria-label="Breadcrumb">
+  <ol class="flex items-center gap-2">
+    @foreach(item in displayItems)
+      <li class="flex items-center gap-2">
+        @if(item.collapsed)
+          <!-- Collapsed indicator -->
+          <span class="{{ collapsedClasses }}">{{ item.label }}</span>
+        @else
+          @if($loop.last)
+            <!-- Last item (current page) -->
+            <span class="{{ activeItemClasses }}" aria-current="page">
+              @if(item.icon)
+                <span class="inline-flex items-center gap-1.5">
+                  <span innerHTML="{!! item.icon !!}"></span>
+                  <span>{{ item.label }}</span>
+                </span>
+              @else
+                {{ item.label }}
+              @endif
+            </span>
+          @else
+            <!-- Link item -->
+            <a
+              href="{{ item.href }}"
+              class="{{ itemClasses }}"
+            >
+              @if(item.icon)
+                <span class="inline-flex items-center gap-1.5">
+                  <span innerHTML="{!! item.icon !!}"></span>
+                  <span>{{ item.label }}</span>
+                </span>
+              @else
+                {{ item.label }}
+              @endif
+            </a>
+          @endif
+        @endif
+
+        <!-- Separator (not after last item) -->
+        @if(!$loop.last)
+          <span class="{{ separatorClasses }}" aria-hidden="true">
+            @if(separator === 'arrow')
+              {!! separatorElement !!}
+            @else
+              {{ separatorElement }}
+            @endif
+          </span>
+        @endif
+      </li>
+    @endforeach
+  </ol>
+</nav>

package/src/ui/breadcrumb/index.ts

@@ -0,0 +1,15 @@
+export { default as Breadcrumb } from './Breadcrumb.stx'
+
+export interface BreadcrumbItem {
+  label: string
+  href: string
+  icon?: string
+  collapsed?: boolean
+}
+
+export interface BreadcrumbProps {
+  items: BreadcrumbItem[]
+  separator?: '/' | '>' | 'arrow' | string
+  maxItems?: number
+  className?: string
+}

package/src/ui/button/Button.stx

@@ -0,0 +1,89 @@
+<script>
+export const variant = $props.variant || 'primary'
+export const size = $props.size || 'md'
+export const disabled = $props.disabled || false
+export const loading = $props.loading || false
+export const type = $props.type || 'button'
+export const fullWidth = $props.fullWidth || false
+export const leftIcon = $props.leftIcon || ''
+export const rightIcon = $props.rightIcon || ''
+export const className = $props.className || ''
+export const onClick = $props.onClick
+
+// Variant styles using headwind
+const variantClasses = {
+  primary: 'bg-blue-500 hover:bg-blue-600 text-white shadow-md hover:shadow-lg dark:bg-blue-600 dark:hover:bg-blue-700',
+  secondary: 'bg-neutral-200 hover:bg-neutral-300 text-neutral-900 dark:bg-neutral-700 dark:hover:bg-neutral-600 dark:text-white',
+  outline: 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50 dark:border-blue-400 dark:text-blue-400 dark:hover:bg-blue-950',
+  ghost: 'hover:bg-neutral-100 text-neutral-700 dark:hover:bg-neutral-800 dark:text-neutral-300',
+  danger: 'bg-red-500 hover:bg-red-600 text-white shadow-md hover:shadow-lg dark:bg-red-600 dark:hover:bg-red-700',
+}
+
+// Size styles using headwind
+const sizeClasses = {
+  xs: 'px-2.5 py-1 text-xs h-7 gap-1',
+  sm: 'px-3 py-1.5 text-sm h-8 gap-1.5',
+  md: 'px-4 py-2 text-base h-10 gap-2',
+  lg: 'px-6 py-3 text-lg h-12 gap-2.5',
+  xl: 'px-8 py-4 text-xl h-14 gap-3',
+}
+
+// Icon size styles
+const iconSizeClasses = {
+  xs: 'h-3 w-3',
+  sm: 'h-4 w-4',
+  md: 'h-5 w-5',
+  lg: 'h-6 w-6',
+  xl: 'h-7 w-7',
+}
+
+// Base classes
+const baseClasses = 'inline-flex items-center justify-center font-semibold rounded-md transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none'
+
+// Width classes
+const widthClasses = fullWidth ? 'w-full' : ''
+
+// Loading state disables interactions
+const isDisabled = disabled || loading
+
+// Combine classes
+export const buttonClasses = `${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${widthClasses} ${className}`.trim()
+export const iconClasses = iconSizeClasses[size]
+export const spinnerClasses = `animate-spin ${iconClasses}`.trim()
+</script>
+
+<button
+  type="{{ type }}"
+  class="{{ buttonClasses }}"
+  @if(isDisabled)disabled@endif
+  @if(onClick)onclick="handleClick(event)"@endif
+  aria-busy="{{ loading ? 'true' : 'false' }}"
+>
+  @if(loading)
+    <!-- Loading spinner -->
+    <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>
+  @else
+    @if(leftIcon)
+      <!-- Left icon -->
+      <span class="{{ iconClasses }}" innerHTML="{!! leftIcon !!}"></span>
+    @endif
+  @endif
+
+  <slot />
+
+  @if(!loading && rightIcon)
+    <!-- Right icon -->
+    <span class="{{ iconClasses }}" innerHTML="{!! rightIcon !!}"></span>
+  @endif
+</button>
+
+<script>
+function handleClick(event) {
+  if (!isDisabled && onClick) {
+    onClick(event)
+  }
+}
+</script>

package/src/ui/button/README.md

@@ -0,0 +1,100 @@
+# Button Component
+
+A versatile button component built with STX and headwind utility classes.
+
+## Installation
+
+```bash
+bun add @stacksjs/components
+```
+
+## Usage
+
+```stx
+@component('Button', { variant: 'primary', size: 'md' })
+  Click me
+@endcomponent
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Button visual style |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `disabled` | `boolean` | `false` | Disable the button |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Button HTML type |
+| `className` | `string` | `''` | Additional CSS classes |
+| `onClick` | `() => void` | - | Click handler |
+
+## Examples
+
+### Variants
+
+```stx
+@component('Button', { variant: 'primary' })
+  Primary Button
+@endcomponent
+
+@component('Button', { variant: 'secondary' })
+  Secondary Button
+@endcomponent
+
+@component('Button', { variant: 'outline' })
+  Outline Button
+@endcomponent
+
+@component('Button', { variant: 'ghost' })
+  Ghost Button
+@endcomponent
+
+@component('Button', { variant: 'danger' })
+  Danger Button
+@endcomponent
+```
+
+### Sizes
+
+```stx
+@component('Button', { size: 'sm' })
+  Small Button
+@endcomponent
+
+@component('Button', { size: 'md' })
+  Medium Button
+@endcomponent
+
+@component('Button', { size: 'lg' })
+  Large Button
+@endcomponent
+```
+
+### Disabled State
+
+```stx
+@component('Button', { disabled: true })
+  Disabled Button
+@endcomponent
+```
+
+### With Icon
+
+```stx
+@component('Button', { variant: 'primary' })
+  <svg class="w-5 h-5 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+  </svg>
+  Add Item
+@endcomponent
+```
+
+## Features
+
+- 5 visual variants (primary, secondary, outline, ghost, danger)
+- 3 size options (sm, md, lg)
+- Disabled state support
+- Focus ring with keyboard navigation
+- Dark mode support
+- Accessible by default
+- Smooth transitions
+- Headwind utility classes for easy customization

package/src/ui/button/index.ts

@@ -0,0 +1,85 @@
+import type { PropSchema, ValidationResult } from '../../utils/prop-validation'
+import { ErrorTypes, wrapErrorHandler } from '../../utils/error-handling'
+import { createPropValidator, PropTypes } from '../../utils/prop-validation'
+
+export { default as Button } from './Button.stx'
+
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger'
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  disabled?: boolean
+  loading?: boolean
+  type?: 'button' | 'submit' | 'reset'
+  fullWidth?: boolean
+  leftIcon?: string
+  rightIcon?: string
+  className?: string
+  onClick?: (event: Event) => void
+}
+
+/**
+ * Button prop validation schema
+ */
+export const buttonPropSchema: PropSchema = {
+  variant: PropTypes.oneOf(['primary', 'secondary', 'outline', 'ghost', 'danger']),
+  size: PropTypes.oneOf(['xs', 'sm', 'md', 'lg', 'xl']),
+  disabled: PropTypes.boolean,
+  loading: PropTypes.boolean,
+  type: PropTypes.oneOf(['button', 'submit', 'reset']),
+  fullWidth: PropTypes.boolean,
+  leftIcon: PropTypes.string,
+  rightIcon: PropTypes.string,
+  className: PropTypes.string,
+  onClick: PropTypes.func,
+}
+
+/**
+ * Validate Button component props
+ * Only runs in development mode
+ */
+export const validateButtonProps: (props: Record<string, any>) => ValidationResult = createPropValidator('Button', buttonPropSchema)
+
+/**
+ * Create a safe onClick handler that catches and reports errors
+ *
+ * @param handler - Click handler function
+ * @returns Wrapped handler with error handling
+ *
+ * @example
+ * ```ts
+ * const safeHandler = createSafeClickHandler(() => {
+ *   // Your click logic
+ * })
+ * ```
+ */
+export function createSafeClickHandler(handler: (event: Event) => void): (event: Event) => void {
+  return wrapErrorHandler(handler, 'Button', 'onClick')
+}
+
+/**
+ * Helper to validate button variant
+ */
+export function validateVariant(variant?: string): void {
+  if (variant && !['primary', 'secondary', 'outline', 'ghost', 'danger'].includes(variant)) {
+    throw ErrorTypes.invalidProp(
+      'Button',
+      'variant',
+      variant,
+      ['primary', 'secondary', 'outline', 'ghost', 'danger'],
+    )
+  }
+}
+
+/**
+ * Helper to validate button size
+ */
+export function validateSize(size?: string): void {
+  if (size && !['xs', 'sm', 'md', 'lg', 'xl'].includes(size)) {
+    throw ErrorTypes.invalidProp(
+      'Button',
+      'size',
+      size,
+      ['xs', 'sm', 'md', 'lg', 'xl'],
+    )
+  }
+}