@stacksjs/stx 0.2.146 → 0.2.147

package/dist/stx.d.ts

@@ -233,11 +233,38 @@ declare function useWebSocket(_url: string, _options?: {
 // Color mode
 // ============================================================================
 
-declare function useColorMode(): {
-  mode: StxSignal<'light' | 'dark' | 'auto'>
-  setMode: (mode: 'light' | 'dark' | 'auto') => void
+interface StxColorModeOptions {
+  /** localStorage key holding the preference. @default 'stx-color-mode' */
+  storageKey?: string
+  /** Mode used when nothing valid is stored. @default 'auto' */
+  initialMode?: 'light' | 'dark' | 'auto'
+  /** Class applied to `<html>` when dark. @default 'dark' */
+  darkClass?: string
+  /** Attribute applied to `<html>` INSTEAD of the class, e.g. 'data-theme'. */
+  attribute?: string
+  /** Suppress CSS transitions across a mode switch. @default true */
+  disableTransitions?: boolean
+}
+
+/**
+ * Omitting the options picks up whatever `app.colorMode` in `stx.config.ts`
+ * published via the pre-paint boot script (stacksjs/stx#1794), so the storage
+ * key and attribute don't have to be repeated at the call site.
+ */
+declare function useColorMode(_options?: StxColorModeOptions): {
+  /** Current resolved mode. */
+  readonly mode: 'light' | 'dark'
+  /** User preference, which may be 'auto'. */
+  readonly preference: 'light' | 'dark' | 'auto'
+  readonly isDark: boolean
+  set: (mode: 'light' | 'dark' | 'auto') => void
+  toggle: () => void
+  subscribe: (fn: (mode: 'light' | 'dark', preference: 'light' | 'dark' | 'auto') => void) => () => void
+}
+declare function useDark(_options?: StxColorModeOptions): StxSignal<boolean> & {
+  readonly isDark: boolean
+  toggle: () => void
 }
-declare function useDark(): StxSignal<boolean>
 declare function useMediaQuery(query: string): StxSignal<boolean> & {
   readonly matches: boolean
   readonly value: boolean
@@ -500,6 +527,7 @@ interface StxRuntimeRegistry {
   useFocus: typeof useFocus
   useAsync: typeof useAsync
   useLocalStorage: typeof useLocalStorage
+  useSessionStorage: typeof useSessionStorage
   useEventListener: typeof useEventListener
   useScrollLock: typeof useScrollLock
   useWebSocket: typeof useWebSocket

package/dist/types/config-types.d.ts

@@ -1,3 +1,4 @@
+import type { ColorModeBootConfig } from '../color-mode-boot';
 import type { ComponentConfig, DocGeneratorConfig, WebComponentConfig } from './component-types';
 import type { CspConfig } from './csp-types';
 import type { CustomDirective, Middleware } from './directive-types';
@@ -250,6 +251,7 @@ export declare interface AppHeadConfig {
 export declare interface StxConfig {
   app?: {
     head?: AppHeadConfig
+    colorMode?: ColorModeBootConfig
     window?: {
       width?: number
       height?: number

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.146",
+  "version": "0.2.147",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -117,12 +117,12 @@
   "dependencies": {
     "@cwcss/crosswind": "^0.2.14",
     "@stacksjs/clapp": "^0.2.0",
-    "@stacksjs/desktop": "0.2.146",
-    "@stacksjs/sanitizer": "0.2.146",
+    "@stacksjs/desktop": "0.2.147",
+    "@stacksjs/sanitizer": "0.2.147",
     "@stacksjs/ts-i18n": "^0.1.11",
-    "bun-plugin-stx": "0.2.146",
+    "bun-plugin-stx": "0.2.147",
     "bunfig": "^0.15.15",
-    "stx-router": "0.2.146",
+    "stx-router": "0.2.147",
     "ts-broadcasting": "^0.0.9",
     "ts-images": "^0.1.9",
     "ts-syntax-highlighter": "^0.2.1"

package/stx.d.ts

@@ -233,11 +233,38 @@ declare function useWebSocket(_url: string, _options?: {
 // Color mode
 // ============================================================================
 
-declare function useColorMode(): {
-  mode: StxSignal<'light' | 'dark' | 'auto'>
-  setMode: (mode: 'light' | 'dark' | 'auto') => void
+interface StxColorModeOptions {
+  /** localStorage key holding the preference. @default 'stx-color-mode' */
+  storageKey?: string
+  /** Mode used when nothing valid is stored. @default 'auto' */
+  initialMode?: 'light' | 'dark' | 'auto'
+  /** Class applied to `<html>` when dark. @default 'dark' */
+  darkClass?: string
+  /** Attribute applied to `<html>` INSTEAD of the class, e.g. 'data-theme'. */
+  attribute?: string
+  /** Suppress CSS transitions across a mode switch. @default true */
+  disableTransitions?: boolean
+}
+
+/**
+ * Omitting the options picks up whatever `app.colorMode` in `stx.config.ts`
+ * published via the pre-paint boot script (stacksjs/stx#1794), so the storage
+ * key and attribute don't have to be repeated at the call site.
+ */
+declare function useColorMode(_options?: StxColorModeOptions): {
+  /** Current resolved mode. */
+  readonly mode: 'light' | 'dark'
+  /** User preference, which may be 'auto'. */
+  readonly preference: 'light' | 'dark' | 'auto'
+  readonly isDark: boolean
+  set: (mode: 'light' | 'dark' | 'auto') => void
+  toggle: () => void
+  subscribe: (fn: (mode: 'light' | 'dark', preference: 'light' | 'dark' | 'auto') => void) => () => void
+}
+declare function useDark(_options?: StxColorModeOptions): StxSignal<boolean> & {
+  readonly isDark: boolean
+  toggle: () => void
 }
-declare function useDark(): StxSignal<boolean>
 declare function useMediaQuery(query: string): StxSignal<boolean> & {
   readonly matches: boolean
   readonly value: boolean
@@ -500,6 +527,7 @@ interface StxRuntimeRegistry {
   useFocus: typeof useFocus
   useAsync: typeof useAsync
   useLocalStorage: typeof useLocalStorage
+  useSessionStorage: typeof useSessionStorage
   useEventListener: typeof useEventListener
   useScrollLock: typeof useScrollLock
   useWebSocket: typeof useWebSocket