@stacksjs/components 0.2.3

package/dist/utils/theme.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Create a custom theme by merging with default theme
+ *
+ * @param customTheme - Partial theme configuration
+ * @returns Complete theme object
+ *
+ * @example
+ * ```ts
+ * const myTheme = createTheme({
+ *   colors: {
+ *     primary: '#3b82f6',
+ *     secondary: '#8b5cf6'
+ *   },
+ *   typography: {
+ *     fontFamily: {
+ *       sans: 'Inter, sans-serif'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function createTheme(customTheme: Partial<Theme>): Theme;
+/**
+ * Get the current active theme
+ *
+ * @returns Current theme object
+ */
+export declare function getTheme(): Theme;
+/**
+ * Convert theme to CSS custom properties
+ *
+ * @param theme - Theme object
+ * @returns CSS custom properties string
+ */
+export declare function themeToCSSProperties(theme: Theme): string;
+/**
+ * Apply theme to the document
+ *
+ * @param theme - Theme object to apply
+ * @param target - Target element (defaults to document.documentElement)
+ *
+ * @example
+ * ```ts
+ * const theme = createTheme({ colors: { primary: '#3b82f6' } })
+ * applyTheme(theme)
+ * ```
+ */
+export declare function applyTheme(theme: Theme, target?: HTMLElement): void;
+/**
+ * Hook to use theme in components
+ *
+ * @returns Current theme object
+ *
+ * @example
+ * ```ts
+ * const theme = useTheme()
+ * const primaryColor = theme.colors.primary
+ * ```
+ */
+export declare function useTheme(): Theme;
+/**
+ * Get a specific theme value by path
+ *
+ * @param path - Dot-notation path to theme value
+ * @returns Theme value or undefined
+ *
+ * @example
+ * ```ts
+ * const primary = getThemeValue('colors.primary')
+ * const fontSize = getThemeValue('typography.fontSize.base')
+ * ```
+ */
+export declare function getThemeValue(path: string): any;
+/**
+ * Generate CSS file content for a theme
+ *
+ * @param theme - Theme object
+ * @returns CSS file content
+ *
+ * @example
+ * ```ts
+ * const theme = createTheme({ colors: { primary: '#3b82f6' } })
+ * const css = generateThemeCSS(theme)
+ * // Write to file or inject into page
+ * ```
+ */
+export declare function generateThemeCSS(theme: Theme): string;
+/**
+ * Default theme
+ */
+export declare const defaultTheme: Theme;
+/**
+ * Predefined theme presets
+ */
+export declare const themePresets: {
+  default: Theme
+  purple: Theme
+  green: Theme
+  orange: Theme
+  dark: Theme
+  minimal: Theme
+};
+/**
+ * Theme system for @stacksjs/components
+ *
+ * Provides customizable color palettes, typography, spacing, and component variants
+ *
+ * @example
+ * ```ts
+ * import { createTheme, applyTheme, useTheme } from '@stacksjs/components'
+ *
+ * const myTheme = createTheme({
+ *   colors: {
+ *     primary: '#3b82f6',
+ *     secondary: '#8b5cf6'
+ *   }
+ * })
+ *
+ * applyTheme(myTheme)
+ * ```
+ */
+/**
+ * Color palette definition
+ */
+export declare interface ColorPalette {
+  primary?: string
+  secondary?: string
+  success?: string
+  warning?: string
+  danger?: string
+  info?: string
+  gray?: string
+  white?: string
+  black?: string
+}
+/**
+ * Typography scale
+ */
+export declare interface Typography {
+  fontFamily?: {
+    sans?: string
+    serif?: string
+    mono?: string
+  }
+  fontSize?: {
+    'xs'?: string
+    'sm'?: string
+    'base'?: string
+    'lg'?: string
+    'xl'?: string
+    '2xl'?: string
+    '3xl'?: string
+    '4xl'?: string
+  }
+  fontWeight?: {
+    light?: string
+    normal?: string
+    medium?: string
+    semibold?: string
+    bold?: string
+  }
+  lineHeight?: {
+    tight?: string
+    normal?: string
+    relaxed?: string
+  }
+}
+/**
+ * Spacing scale
+ */
+export declare interface Spacing {
+  'xs'?: string
+  'sm'?: string
+  'md'?: string
+  'lg'?: string
+  'xl'?: string
+  '2xl'?: string
+  '3xl'?: string
+  '4xl'?: string
+}
+/**
+ * Border radius scale
+ */
+export declare interface BorderRadius {
+  none?: string
+  sm?: string
+  md?: string
+  lg?: string
+  full?: string
+}
+/**
+ * Shadow scale
+ */
+export declare interface Shadows {
+  'sm'?: string
+  'md'?: string
+  'lg'?: string
+  'xl'?: string
+  '2xl'?: string
+  'none'?: string
+}
+/**
+ * Component-specific overrides
+ */
+export declare interface ComponentOverrides {
+  button?: {
+    borderRadius?: string
+    padding?: string
+    fontSize?: string
+    fontWeight?: string
+  }
+  input?: {
+    borderRadius?: string
+    padding?: string
+    fontSize?: string
+    borderWidth?: string
+  }
+  card?: {
+    borderRadius?: string
+    padding?: string
+    shadow?: string
+  }
+}
+/**
+ * Complete theme configuration
+ */
+export declare interface Theme {
+  colors: ColorPalette
+  typography: Typography
+  spacing: Spacing
+  borderRadius: BorderRadius
+  shadows: Shadows
+  components?: ComponentOverrides
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@stacksjs/components",
+  "type": "module",
+  "version": "0.2.3",
+  "description": "A modern component library built with STX, featuring headwind utility classes and TypeScript syntax highlighting.",
+  "author": "Chris Breuer <chris@stacksjs.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/stacksjs/stx/tree/main/packages/components#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stx.git",
+    "directory": "./packages/components"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stx/issues"
+  },
+  "keywords": [
+    "components",
+    "ui",
+    "stx",
+    "headwind",
+    "typescript",
+    "bun",
+    "component-library"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "import": "./dist/*/index.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun --bun build.ts",
+    "dev": "bun --bun build.ts --watch",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "lint": "bunx --bun pickier lint",
+    "lint:fix": "bunx --bun pickier lint --fix",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@stacksjs/headwind": "^0.1.3",
+    "@stacksjs/stx": "workspace:*",
+    "bun-plugin-stx": "workspace:*",
+    "ts-syntax-highlighter": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "bun-plugin-dtsx": "^0.9.9",
+    "pickier": "^0.1.10",
+    "typescript": "^5.9.3"
+  }
+}

package/src/components/CodeBlock.stx

@@ -0,0 +1,57 @@
+<script>
+import { highlight, applyHeadwindClasses } from '../utils/highlighter'
+
+export const code = $props.code || ''
+export const language = $props.language || 'typescript'
+export const theme = $props.theme || 'auto'
+export const lineNumbers = $props.lineNumbers !== false
+export const copyable = $props.copyable !== false
+export const className = $props.className || ''
+
+export let highlightedCode = ''
+export let copied = false
+
+// Highlight the code
+const result = await highlight(code, { language, theme, lineNumbers })
+highlightedCode = applyHeadwindClasses(result.html, className)
+
+export async function copyToClipboard() {
+  try {
+    await navigator.clipboard.writeText(code)
+    copied = true
+    setTimeout(() => {
+      copied = false
+    }, 2000)
+  } catch (err) {
+    console.error('Failed to copy code:', err)
+  }
+}
+</script>
+
+<div class="relative group">
+  {!! highlightedCode !!}
+
+  @if(copyable)
+    <button
+      @click="copyToClipboard"
+      class="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity duration-200 px-3 py-1.5 bg-neutral-800 hover:bg-neutral-700 text-white text-xs rounded-md font-medium"
+      aria-label="Copy code"
+    >
+      @if(copied)
+        <span class="flex items-center gap-1.5">
+          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
+          </svg>
+          Copied!
+        </span>
+      @else
+        <span class="flex items-center gap-1.5">
+          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+          </svg>
+          Copy
+        </span>
+      @endif
+    </button>
+  @endif
+</div>

package/src/components/Footer.stx

@@ -0,0 +1,66 @@
+<script>
+export const author = $props.author || '@chrisbbreuer'
+export const authorUrl = $props.authorUrl || 'https://github.com/chrisbbreuer'
+export const project = $props.project || '@stacksjs'
+export const projectUrl = $props.projectUrl || 'https://github.com/stacksjs/stacks'
+export const twitterUrl = $props.twitterUrl || 'https://twitter.com/chrisbbreuer'
+export const sponsorUrl = $props.sponsorUrl || 'https://github.com/sponsors/chrisbbreuer'
+export const coffeeUrl = $props.coffeeUrl || 'https://www.buymeacoffee.com/xlbd'
+
+export const currentYear = new Date().getFullYear()
+</script>
+
+<footer class="flex items-center justify-center mt-16 w-full pb-4 text-neutral-600 dark:text-neutral-400 opacity-60">
+  <div class="flex flex-col items-center justify-center">
+    <p class="text-sm">
+      With 💙 by
+      <a href="{{ authorUrl }}" class="text-blue-500 hover:text-blue-600 dark:text-blue-400 dark:hover:text-blue-300 transition-colors">
+        {{ author }}
+      </a>
+      &
+      <a href="{{ projectUrl }}" class="text-blue-500 hover:text-blue-600 dark:text-blue-400 dark:hover:text-blue-300 transition-colors">
+        {{ project }}
+      </a>
+      <span> © {{ currentYear }}</span>
+    </p>
+
+    <div class="mt-2 flex flex-col items-center sm:flex-row space-x-1 space-y-2 sm:space-y-0">
+      <div class="flex items-center space-x-1">
+        <svg class="w-4 h-4 text-blue-500" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M8.29 20.251c7.547 0 11.675-6.253 11.675-11.675 0-.178 0-.355-.012-.53A8.348 8.348 0 0022 5.92a8.19 8.19 0 01-2.357.646 4.118 4.118 0 001.804-2.27 8.224 8.224 0 01-2.605.996 4.107 4.107 0 00-6.993 3.743 11.65 11.65 0 01-8.457-4.287 4.106 4.106 0 001.27 5.477A4.072 4.072 0 012.8 9.713v.052a4.105 4.105 0 003.292 4.022 4.095 4.095 0 01-1.853.07 4.108 4.108 0 003.834 2.85A8.233 8.233 0 012 18.407a11.616 11.616 0 006.29 1.84" />
+        </svg>
+        <span class="text-sm">
+          <a href="{{ twitterUrl }}" target="_blank" rel="noopener noreferrer" class="text-blue-500 hover:text-blue-600 dark:text-blue-400 dark:hover:text-blue-300 transition-colors">
+            Follow me on Twitter
+          </a>
+        </span>
+      </div>
+
+      <span class="hidden px-2 text-neutral-400 sm:block">|</span>
+
+      <div class="flex items-center space-x-1">
+        <svg class="w-4 h-4 text-blue-500" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M20.216 6.415l-.132-.666c-.119-.598-.388-1.163-1.001-1.379-.197-.069-.42-.098-.57-.241-.152-.143-.196-.366-.231-.572-.065-.378-.125-.756-.192-1.133-.057-.325-.102-.69-.25-.987-.195-.4-.597-.634-.996-.788a5.723 5.723 0 00-.626-.194c-1-.263-2.05-.36-3.077-.416a25.834 25.834 0 00-3.7.062c-.915.083-1.88.184-2.75.5-.318.116-.646.256-.888.501-.297.302-.393.77-.177 1.146.154.267.415.456.692.58.36.162.737.284 1.123.366 1.075.238 2.189.331 3.287.37 1.218.05 2.437.01 3.65-.118.299-.033.598-.073.896-.119.352-.054.578-.513.474-.834-.124-.383-.457-.531-.834-.473-.466.074-.96.108-1.382.146-1.177.08-2.358.082-3.536.006a22.228 22.228 0 01-1.157-.107c-.086-.01-.18-.025-.258-.036-.243-.036-.484-.08-.724-.13-.111-.027-.111-.185 0-.212h.005c.277-.06.557-.108.838-.147h.002c.131-.009.263-.032.394-.048a25.076 25.076 0 013.426-.12c.674.019 1.347.067 2.017.144l.228.031c.267.04.533.088.798.145.392.085.895.113 1.07.542.055.137.08.288.111.431l.319 1.484a.237.237 0 01-.199.284h-.003c-.037.006-.075.01-.112.015a36.704 36.704 0 01-4.743.295 37.059 37.059 0 01-4.699-.304c-.14-.017-.293-.042-.417-.06-.326-.048-.649-.108-.973-.161-.393-.065-.768-.032-1.123.161-.29.16-.527.404-.675.701-.154.316-.199.66-.267 1-.069.34-.176.707-.135 1.056.087.753.613 1.365 1.37 1.502a39.69 39.69 0 0011.343.376.483.483 0 01.535.53l-.071.697-1.018 9.907c-.041.41-.047.832-.125 1.237-.122.637-.553 1.028-1.182 1.171-.577.131-1.165.2-1.756.205-.656.004-1.31-.025-1.966-.022-.699.004-1.556-.06-2.095-.58-.475-.458-.54-1.174-.605-1.793l-.731-7.013-.322-3.094c-.037-.351-.286-.695-.678-.678-.336.015-.718.3-.678.679l.228 2.185.949 9.112c.147 1.344 1.174 2.068 2.446 2.272.742.12 1.503.144 2.257.156.966.016 1.942.053 2.892-.122 1.408-.258 2.465-1.198 2.616-2.657.34-3.332.683-6.663 1.024-9.995l.215-2.087a.484.484 0 01.39-.426c.402-.078.787-.212 1.074-.518.455-.488.546-1.124.385-1.766zm-1.478.772c-.145.137-.363.201-.578.233-2.416.359-4.866.54-7.308.46-1.748-.06-3.477-.254-5.207-.498-.17-.024-.353-.055-.47-.18-.22-.236-.111-.71-.054-.995.052-.26.152-.609.463-.646.484-.057 1.046.148 1.526.22.577.088 1.156.16 1.737.212 2.48.226 5.002.19 7.472-.14.45-.06.899-.13 1.345-.21.399-.072.84-.206 1.08.206.166.281.188.657.162.974a.544.544 0 01-.169.364zm-6.159 3.9c-.862.37-1.84.788-3.109.788a5.884 5.884 0 01-1.569-.217l.877 9.004c.065.78.717 1.38 1.5 1.38 0 0 1.243.065 1.658.065.447 0 1.786-.065 1.786-.065.783 0 1.434-.6 1.499-1.38l.94-9.95a3.996 3.996 0 00-1.322-.238c-.826 0-1.491.284-2.26.613z" />
+        </svg>
+        <span class="text-sm">
+          <a href="{{ coffeeUrl }}" target="_blank" rel="noopener noreferrer" class="text-blue-500 hover:text-blue-600 dark:text-blue-400 dark:hover:text-blue-300 transition-colors">
+            Buy me a coffee
+          </a>
+        </span>
+      </div>
+
+      <span class="hidden px-2 text-neutral-400 sm:block">|</span>
+
+      <div class="flex items-center space-x-1">
+        <svg class="w-4 h-4 text-blue-500" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="m11.645 20.91-.007-.003-.022-.012a15.247 15.247 0 0 1-.383-.218 25.18 25.18 0 0 1-4.244-3.17C4.688 15.36 2.25 12.174 2.25 8.25 2.25 5.322 4.714 3 7.688 3A5.5 5.5 0 0 1 12 5.052 5.5 5.5 0 0 1 16.313 3c2.973 0 5.437 2.322 5.437 5.25 0 3.925-2.438 7.111-4.739 9.256a25.175 25.175 0 0 1-4.244 3.17 15.247 15.247 0 0 1-.383.219l-.022.012-.007.004-.003.001a.752.752 0 0 1-.704 0l-.003-.001Z" />
+        </svg>
+        <span class="text-sm">
+          <a href="{{ sponsorUrl }}" target="_blank" rel="noopener noreferrer" class="text-blue-500 hover:text-blue-600 dark:text-blue-400 dark:hover:text-blue-300 transition-colors">
+            Sponsor me on GitHub
+          </a>
+        </span>
+      </div>
+    </div>
+  </div>
+</footer>

package/src/components/Hero.stx

@@ -0,0 +1,25 @@
+<script>
+export const title = $props.title || 'Component'
+export const description = $props.description || 'A modern component built with STX'
+export const githubUrl = $props.githubUrl || '#'
+</script>
+
+<div class="flex flex-col items-center gap-3">
+  <h1 class="text-5xl font-bold mb-3 -mt-5 bg-gradient-to-r from-blue-500 to-purple-600 bg-clip-text text-transparent">
+    {{ title }}
+  </h1>
+  <p class="mb-3 mt-0 text-lg text-neutral-600 dark:text-neutral-400">
+    {{ description }}
+  </p>
+  <div class="flex gap-2">
+    <slot name="demo" />
+    <a
+      href="{{ githubUrl }}"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="inline-flex items-center justify-center h-10 px-8 rounded-md text-sm font-semibold bg-gradient-to-b from-white to-neutral-100 dark:from-neutral-800 dark:to-neutral-900 text-neutral-900 dark:text-white shadow-md hover:shadow-lg transition-all duration-200"
+    >
+      GitHub
+    </a>
+  </div>
+</div>

package/src/components/Installation.stx

@@ -0,0 +1,39 @@
+<script>
+import { CodeBlock } from './CodeBlock.stx'
+
+export const packageName = $props.packageName || '@stacksjs/component'
+export const installCode = `bun add ${packageName}`
+export const npmCode = `npm install ${packageName}`
+export const pnpmCode = `pnpm add ${packageName}`
+export const yarnCode = `yarn add ${packageName}`
+</script>
+
+<div class="installation">
+  <h2 class="my-2 text-lg font-semibold">Installation</h2>
+
+  <p class="my-3 text-base">
+    Install the component using your preferred package manager:
+  </p>
+
+  <div class="space-y-4">
+    <div>
+      <h3 class="text-sm font-medium mb-2 text-neutral-700 dark:text-neutral-300">Bun (recommended)</h3>
+      @component('CodeBlock', { code: installCode, language: 'bash' })
+    </div>
+
+    <div>
+      <h3 class="text-sm font-medium mb-2 text-neutral-700 dark:text-neutral-300">npm</h3>
+      @component('CodeBlock', { code: npmCode, language: 'bash' })
+    </div>
+
+    <div>
+      <h3 class="text-sm font-medium mb-2 text-neutral-700 dark:text-neutral-300">pnpm</h3>
+      @component('CodeBlock', { code: pnpmCode, language: 'bash' })
+    </div>
+
+    <div>
+      <h3 class="text-sm font-medium mb-2 text-neutral-700 dark:text-neutral-300">Yarn</h3>
+      @component('CodeBlock', { code: yarnCode, language: 'bash' })
+    </div>
+  </div>
+</div>

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { default as CodeBlock } from './CodeBlock.stx'
+export { default as Footer } from './Footer.stx'
+export { default as Hero } from './Hero.stx'
+export { default as Installation } from './Installation.stx'

package/src/composables/index.ts

@@ -0,0 +1,4 @@
+export * from './useCopyCode'
+export * from './useDarkMode'
+export * from './useSEO'
+export * from './utilities'

package/src/composables/useCopyCode.ts

@@ -0,0 +1,73 @@
+/**
+ * Copy code to clipboard with visual feedback
+ */
+export interface CopyCodeOptions {
+  code: string
+  onSuccess?: () => void
+  onError?: (error: Error) => void
+  timeout?: number
+}
+
+export interface CopyCodeResult {
+  copied: boolean
+  copy: () => Promise<void>
+  reset: () => void
+}
+
+export function useCopyCode(options: CopyCodeOptions): CopyCodeResult {
+  const { code, onSuccess, onError, timeout = 2000 } = options
+
+  let copied = false
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+
+  const reset = () => {
+    copied = false
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+      timeoutId = null
+    }
+  }
+
+  const copy = async () => {
+    try {
+      if (!navigator.clipboard) {
+        throw new Error('Clipboard API not available')
+      }
+
+      await navigator.clipboard.writeText(code)
+      copied = true
+      onSuccess?.()
+
+      // Auto-reset after timeout
+      timeoutId = setTimeout(() => {
+        copied = false
+        timeoutId = null
+      }, timeout)
+    }
+    catch (error) {
+      const err = error instanceof Error ? error : new Error('Failed to copy code')
+      onError?.(err)
+      console.error('Failed to copy code:', err)
+    }
+  }
+
+  return {
+    copied,
+    copy,
+    reset,
+  }
+}
+
+/**
+ * Simple synchronous copy function for direct use
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text)
+    return true
+  }
+  catch (error) {
+    console.error('Failed to copy to clipboard:', error)
+    return false
+  }
+}

package/src/composables/useDarkMode.ts

@@ -0,0 +1,100 @@
+/**
+ * Dark mode utilities for STX components
+ */
+
+export interface DarkModeOptions {
+  storageKey?: string
+  defaultTheme?: 'light' | 'dark' | 'system'
+}
+
+export interface DarkModeResult {
+  isDark: boolean
+  theme: 'light' | 'dark' | 'system'
+  toggle: () => void
+  setTheme: (theme: 'light' | 'dark' | 'system') => void
+}
+
+/**
+ * Check if system prefers dark mode
+ */
+export function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined')
+    return 'light'
+
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+/**
+ * Get the effective theme (resolving 'system' to actual theme)
+ */
+export function getEffectiveTheme(theme: 'light' | 'dark' | 'system'): 'light' | 'dark' {
+  return theme === 'system' ? getSystemTheme() : theme
+}
+
+/**
+ * Use dark mode hook
+ */
+export function useDarkMode(options: DarkModeOptions = {}): DarkModeResult {
+  const { storageKey = 'theme', defaultTheme = 'system' } = options
+
+  // Get initial theme from storage or use default
+  let theme: 'light' | 'dark' | 'system' = defaultTheme
+
+  if (typeof window !== 'undefined' && typeof localStorage !== 'undefined') {
+    const stored = localStorage.getItem(storageKey) as 'light' | 'dark' | 'system' | null
+    if (stored)
+      theme = stored
+  }
+
+  const isDark = getEffectiveTheme(theme) === 'dark'
+
+  // Apply theme to document
+  const applyTheme = (newTheme: 'light' | 'dark' | 'system') => {
+    const effective = getEffectiveTheme(newTheme)
+
+    if (typeof document !== 'undefined') {
+      if (effective === 'dark') {
+        document.documentElement.classList.add('dark')
+      }
+      else {
+        document.documentElement.classList.remove('dark')
+      }
+    }
+
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(storageKey, newTheme)
+    }
+  }
+
+  // Set theme
+  const setTheme = (newTheme: 'light' | 'dark' | 'system') => {
+    theme = newTheme
+    applyTheme(newTheme)
+  }
+
+  // Toggle between light and dark
+  const toggle = () => {
+    const currentEffective = getEffectiveTheme(theme)
+    const newTheme = currentEffective === 'dark' ? 'light' : 'dark'
+    setTheme(newTheme)
+  }
+
+  // Apply initial theme
+  applyTheme(theme)
+
+  // Listen for system theme changes if using system theme
+  if (typeof window !== 'undefined' && theme === 'system') {
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (_e) => {
+      if (theme === 'system') {
+        applyTheme('system')
+      }
+    })
+  }
+
+  return {
+    isDark,
+    theme,
+    toggle,
+    setTheme,
+  }
+}