@stacksjs/stx 0.2.151 → 0.2.152

package/dist/component-processing.d.ts

@@ -38,6 +38,22 @@ export declare function findComponentTags(html: string, tagPattern: RegExp, skip
  * A legacy HTML-entity-escaped JSON format is still accepted as a fallback so
  * that any externally-produced markup keeps working.
  */
+/**
+ * Decode the entities in a static attribute value.
+ *
+ * An attribute in a template is HTML source, so `title="Tom & Jerry"` names
+ * the string `Tom & Jerry`, and a component that receives it as a prop should
+ * see that string rather than the encoding of it.
+ *
+ * The narrowness is the point. This runs on attribute values, at parse time, and
+ * on nothing else: a value that reached a component any other way - from the
+ * component's own script, from the parent's context, from a `:bound="expression"`
+ * - was never encoded, so decoding it can only destroy escaping somebody meant.
+ * That is exactly what a blanket "this looks like HTML, unescape it" pass over
+ * the component context used to do, and it turned escaped user text back into
+ * live markup.
+ */
+export declare function decodeAttributeEntities(value: string): string;
 export declare function decodeStxProp(attrValue: string, options?: { debug?: boolean }): unknown;
 /**
  * Parse multiline attributes from a component tag

package/dist/component-processing.js

@@ -113,6 +113,9 @@ export function findComponentTags(html, tagPattern, skipTags) {
   }
   return matches;
 }
+export function decodeAttributeEntities(value) {
+  return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#0?39;/g, "'").replace(/&#x27;/gi, "'").replace(/&amp;/g, "&");
+}
 export function decodeStxProp(attrValue, options) {
   try {
     const json = Buffer.from(attrValue, "base64").toString("utf8");
@@ -606,7 +609,7 @@ export async function processCustomElements(template, context, filePath, compone
             props[attrName] = result;
           }
         } else
-          props[attrName] = attrValue;
+          props[attrName] = decodeAttributeEntities(attrValue);
       }
       const processedContent = await renderComponentWithSlot(componentPath, props, tag.content, componentsDir, context, filePath, options, processedComponents, dependencies);
       result = result.substring(0, tag.startIndex) + processedContent + result.substring(tag.endIndex);

package/dist/component-renderer.js

@@ -1,6 +1,6 @@
 import { registry } from "./component-registry.js";
 import { registerBuiltins } from "./builtins/index.js";
-import { decodeStxProp, findComponentTags, parseMultilineAttributes, pascalToKebab, restoreStashedScripts, stashScriptElements } from "./component-processing.js";
+import { decodeAttributeEntities, decodeStxProp, findComponentTags, parseMultilineAttributes, pascalToKebab, restoreStashedScripts, stashScriptElements } from "./component-processing.js";
 import { maskAtElementPosition, matchHtmlComment } from "./html-masking.js";
 import { renderComponentWithSlot, userComponentFileExists } from "./utils.js";
 import { createSafeFunction, isExpressionSafe, safeEvaluateObject } from "./safe-evaluator.js";
@@ -287,7 +287,7 @@ function parseComponentProps(rawProps, context, options) {
       }
       continue;
     }
-    setStatic(attrName, attrValue === BOOLEAN_ATTRIBUTE_SENTINEL ? "true" : attrValue);
+    setStatic(attrName, attrValue === BOOLEAN_ATTRIBUTE_SENTINEL ? "true" : decodeAttributeEntities(attrValue));
   }
   return resolved;
 }

package/dist/composables/use-device-orientation.d.ts

@@ -63,7 +63,7 @@ export declare function useDeviceMotion(): DeviceMotionRef;
  * })
  * ```
  */
-export declare function useParallax(): void;
+export declare function useParallax(): ParallaxRef;
 /**
  * Device Orientation & Motion Composables
  *
@@ -101,6 +101,13 @@ export declare interface DeviceOrientationRef {
   isSupported: () => boolean
   requestPermission: () => Promise<boolean>
 }
+/** Handle returned by {@link useParallax}. */
+export declare interface ParallaxRef {
+  get: () => { x: number, y: number }
+  subscribe: (fn: (state: { x: number, y: number }) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}
 export declare interface DeviceMotionRef {
   get: () => DeviceMotionState
   subscribe: (fn: (state: DeviceMotionState) => void) => () => void

package/dist/composables/use-event-source.d.ts

@@ -40,7 +40,7 @@ export declare function useEventSource<T = unknown>(url: string | URL, options?:
  * })
  * ```
  */
-export declare function useSSE<T = unknown>(url: string): void;
+export declare function useSSE<T = unknown>(url: string): SSERef<T>;
 export declare interface EventSourceState<T = unknown> {
   status: EventSourceStatus
   data: T | null
@@ -61,6 +61,19 @@ export declare interface EventSourceOptions {
   onMessage?: (event: MessageEvent) => void
   onError?: (event: Event) => void
 }
+/** Handle returned by {@link useSSE}. */
+export declare interface SSERef<T = unknown> {
+  data: {
+    get: () => T | null
+    subscribe: (fn: (data: T | null) => void) => () => void
+  }
+  status: {
+    get: () => EventSourceStatus
+    subscribe: (fn: (status: EventSourceStatus) => void) => () => void
+  }
+  close: () => void
+  open: () => void
+}
 export declare interface EventSourceRef<T = unknown> {
   get: () => EventSourceState<T>
   subscribe: (fn: (state: EventSourceState<T>) => void) => () => void

package/dist/composables/use-eye-dropper.d.ts

@@ -69,7 +69,7 @@ export declare function hexToHsl(hex: string): { h: number, s: number, l: number
 export declare function useColorHistory(options?: {
   maxHistory?: number
   onPick?: (color: string) => void
-}): void;
+}): ColorHistoryRef;
 /**
  * EyeDropper Composables
  *
@@ -89,6 +89,15 @@ export declare interface EyeDropperOptions {
   onAbort?: () => void
   onError?: (error: Error) => void
 }
+/** Handle returned by {@link useColorHistory}. */
+export declare interface ColorHistoryRef {
+  get: () => { current: string | null, history: string[] }
+  subscribe: (fn: (state: { current: string | null, history: string[] }) => void) => () => void
+  pick: () => Promise<string | null>
+  clearHistory: () => void
+  removeFromHistory: (color: string) => void
+  isSupported: () => boolean
+}
 export declare interface EyeDropperRef {
   get: () => EyeDropperState
   subscribe: (fn: (state: EyeDropperState) => void) => () => void

package/dist/composables/use-idle.d.ts

@@ -32,7 +32,7 @@ export declare function useIdle(options?: IdleOptions): IdleRef;
  * })
  * ```
  */
-export declare function useIdleState(timeout?: number): void;
+export declare function useIdleState(timeout?: number): IdleStateRef;
 /**
  * Track user's last active timestamp
  *
@@ -45,7 +45,7 @@ export declare function useIdleState(timeout?: number): void;
  * })
  * ```
  */
-export declare function useLastActive(): void;
+export declare function useLastActive(): LastActiveRef;
 /**
  * Auto-logout after idle timeout
  *
@@ -57,7 +57,7 @@ export declare function useLastActive(): void;
  * })
  * ```
  */
-export declare function useAutoLogout(timeout: number, onLogout: () => void, options?: { warningTime?: number, onWarning?: (remainingTime: number) => void }): void;
+export declare function useAutoLogout(timeout: number, onLogout: () => void, options?: { warningTime?: number, onWarning?: (remainingTime: number) => void }): AutoLogoutRef;
 /**
  * Idle Detection Composables
  *
@@ -82,3 +82,21 @@ export declare interface IdleRef {
   reset: () => void
   isIdle: () => boolean
 }
+/** Narrowed view of {@link IdleRef} exposing only the idle flag. */
+export declare interface IdleStateRef {
+  get: () => boolean
+  subscribe: (fn: (isIdle: boolean) => void) => () => void
+  reset: () => void
+}
+/** Narrowed view of {@link IdleRef} exposing only the last-active timestamp. */
+export declare interface LastActiveRef {
+  get: () => number
+  subscribe: (fn: (timestamp: number) => void) => () => void
+  reset: () => void
+}
+/** Handle returned by {@link useAutoLogout}. */
+export declare interface AutoLogoutRef {
+  get: () => IdleState
+  subscribe: (fn: (state: IdleState) => void) => () => void
+  reset: () => void
+}

package/dist/composables/use-storage.d.ts

@@ -20,12 +20,18 @@
 export declare function useStorage<T>(key: string, defaultValue: T, options?: UseStorageOptions<T>): StorageRef<T>;
 /**
  * Shorthand for useStorage with localStorage
+ *
+ * The return type is annotated rather than inferred on purpose: the shipped
+ * declarations are emitted by bun-plugin-dtsx, which resolves an unannotated
+ * export to `void`. Consumers importing from `@stacksjs/stx/composables` then
+ * got `Property 'value' does not exist on type 'void'` for a function that
+ * plainly returns a StorageRef. See stacksjs/stx#1796.
  */
-export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): void;
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T>;
 /**
  * Shorthand for useStorage with sessionStorage
  */
-export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): void;
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T>;
 /**
  * Clear all items from storage
  */

package/dist/composables/use-text-selection.d.ts

@@ -36,7 +36,7 @@ export declare function useTextSelection(options?: TextSelectionOptions): TextSe
  * })
  * ```
  */
-export declare function useElementTextSelection(element: Element | null): void;
+export declare function useElementTextSelection(element: Element | null): ElementTextSelectionRef;
 /**
  * Create a selection popup that appears when text is selected
  *
@@ -56,7 +56,7 @@ export declare function useSelectionPopup(options: {
   onShow?: (text: string, position: { x: number, y: number }) => void
   onHide?: () => void
   minLength?: number
-}): void;
+}): SelectionPopupRef;
 /**
  * Copy selected text to clipboard with custom formatting
  *
@@ -71,7 +71,7 @@ export declare function useSelectionPopup(options: {
  * copy.copyWithPrefix('> ')
  * ```
  */
-export declare function useCopySelection(): void;
+export declare function useCopySelection(): CopySelectionRef;
 /**
  * Text Selection Composables
  *
@@ -87,6 +87,30 @@ export declare interface TextSelectionOptions {
   onSelect?: (state: TextSelectionState) => void
   onClear?: () => void
 }
+/** Handle returned by {@link useElementTextSelection}. */
+export declare interface ElementTextSelectionRef {
+  get: () => string
+  subscribe: (fn: (text: string) => void) => () => void
+  clear: () => void
+  selectAll: () => void
+}
+/** Handle returned by {@link useSelectionPopup}. */
+export declare interface SelectionPopupRef {
+  get: () => TextSelectionState
+  subscribe: (fn: (state: TextSelectionState) => void) => () => void
+  isShowing: () => boolean
+}
+/** Handle returned by {@link useCopySelection}. */
+export declare interface CopySelectionRef {
+  get: () => TextSelectionState
+  subscribe: (fn: (state: TextSelectionState) => void) => () => void
+  copy: () => Promise<boolean>
+  copyAsMarkdown: () => Promise<boolean>
+  copyWithPrefix: (prefix: string) => Promise<boolean>
+  copyWithWrapper: (start: string, end: string) => Promise<boolean>
+  getText: () => string
+  clear: () => void
+}
 export declare interface TextSelectionRef {
   get: () => TextSelectionState
   subscribe: (fn: (state: TextSelectionState) => void) => () => void

package/dist/composables/use-wake-lock.d.ts

@@ -43,7 +43,7 @@ export declare function useWakeLock(): WakeLockRef;
  * })
  * ```
  */
-export declare function useAutoWakeLock(): void;
+export declare function useAutoWakeLock(): WakeLockRef;
 /**
  * Wake lock that only activates while a condition is true
  *
@@ -62,7 +62,7 @@ export declare function useAutoWakeLock(): void;
  * wakeLock.check() // Releases wake lock
  * ```
  */
-export declare function useConditionalWakeLock(condition: () => boolean): void;
+export declare function useConditionalWakeLock(condition: () => boolean): WakeLockRef & { check: () => Promise<void> };
 /**
  * Wake Lock Composables
  *