@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/composables/use-window.js

@@ -0,0 +1,163 @@
+export function useWindowSize() {
+  const subscribers = new Set, isClient = typeof window < "u";
+  let currentSize = {
+    width: isClient ? window.innerWidth : 0,
+    height: isClient ? window.innerHeight : 0
+  };
+  if (isClient) {
+    const handler = () => {
+      currentSize = {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      for (const callback of subscribers)
+        try {
+          callback(currentSize);
+        } catch (e) {
+          console.error("[useWindowSize] Subscriber error:", e);
+        }
+    };
+    window.addEventListener("resize", handler, { passive: !0 });
+  }
+  return {
+    get width() {
+      return currentSize.width;
+    },
+    get height() {
+      return currentSize.height;
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      callback(currentSize);
+      return () => subscribers.delete(callback);
+    }
+  };
+}
+export function useScroll() {
+  const subscribers = new Set, isClient = typeof window < "u";
+  let currentPosition = {
+    x: isClient ? window.scrollX : 0,
+    y: isClient ? window.scrollY : 0
+  };
+  if (isClient) {
+    const handler = () => {
+      currentPosition = {
+        x: window.scrollX,
+        y: window.scrollY
+      };
+      for (const callback of subscribers)
+        try {
+          callback(currentPosition);
+        } catch (e) {
+          console.error("[useScroll] Subscriber error:", e);
+        }
+    };
+    window.addEventListener("scroll", handler, { passive: !0 });
+  }
+  return {
+    get x() {
+      return currentPosition.x;
+    },
+    get y() {
+      return currentPosition.y;
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      callback(currentPosition);
+      return () => subscribers.delete(callback);
+    },
+    scrollTo: (options, y) => {
+      if (!isClient)
+        return;
+      if (typeof options === "number")
+        window.scrollTo(options, y ?? 0);
+      else
+        window.scrollTo(options);
+    },
+    scrollToTop: () => {
+      if (!isClient)
+        return;
+      window.scrollTo({ top: 0, behavior: "smooth" });
+    },
+    scrollToBottom: () => {
+      if (!isClient)
+        return;
+      window.scrollTo({ top: document.body.scrollHeight, behavior: "smooth" });
+    }
+  };
+}
+export function useVisibility() {
+  const subscribers = new Set, isClient = typeof document < "u";
+  let isVisible = isClient ? document.visibilityState === "visible" : !0;
+  if (isClient)
+    document.addEventListener("visibilitychange", () => {
+      isVisible = document.visibilityState === "visible";
+      for (const callback of subscribers)
+        try {
+          callback(isVisible);
+        } catch (e) {
+          console.error("[useVisibility] Subscriber error:", e);
+        }
+    });
+  return {
+    get isVisible() {
+      return isVisible;
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      callback(isVisible);
+      return () => subscribers.delete(callback);
+    }
+  };
+}
+export function useTitle(initialTitle) {
+  const isClient = typeof document < "u";
+  if (initialTitle && isClient)
+    document.title = initialTitle;
+  return {
+    get value() {
+      return isClient ? document.title : "";
+    },
+    set value(newTitle) {
+      if (isClient)
+        document.title = newTitle;
+    },
+    set: (title) => {
+      if (isClient)
+        document.title = title;
+    }
+  };
+}
+export function useFavicon(href) {
+  const isClient = typeof document < "u", getLinkElement = () => {
+    if (!isClient)
+      return null;
+    let link = document.querySelector('link[rel*="icon"]');
+    if (!link) {
+      link = document.createElement("link");
+      link.rel = "icon";
+      document.head.appendChild(link);
+    }
+    return link;
+  };
+  if (href) {
+    const link = getLinkElement();
+    if (link)
+      link.href = href;
+  }
+  return {
+    get value() {
+      return getLinkElement()?.href || "";
+    },
+    set value(newHref) {
+      const link = getLinkElement();
+      if (link)
+        link.href = newHref;
+    },
+    set: (newHref) => {
+      const link = getLinkElement();
+      if (link)
+        link.href = newHref;
+    }
+  };
+}

package/dist/composables.d.ts

@@ -0,0 +1,287 @@
+/**
+ * STX Composables
+ *
+ * Vue-inspired composable utilities for STX components:
+ * - Lifecycle hooks (onMount, onDestroy, onUpdate)
+ * - Refs for DOM element references
+ * - Watch and computed for reactivity
+ *
+ * @module composables
+ */
+export type CleanupFn = () => void;
+/**
+ * A lifecycle hook may be `async`.
+ *
+ * `onMount(async () => { data.set(await load()) })` is the documented way to
+ * fetch a component's initial data, and the signals API has always typed it
+ * that way. This declaration used to allow only a synchronous hook, so every
+ * async `onMount` in a real app was a type error against an API that ran it
+ * fine. Only a *synchronous* return can be a cleanup function - the runtime
+ * registers it before the next hook runs - so a promise resolves to `void`.
+ */
+export type LifecycleHook = () => void | CleanupFn | Promise<void>;
+export type WatchCallback<T> = (newValue: T, oldValue: T | undefined) => void | CleanupFn;
+export type WatchSource<T> = () => T;
+export interface Ref<T> {
+    value: T | null;
+    readonly current: T | null;
+}
+export interface ComponentInstance {
+    id: string;
+    element: Element | null;
+    mountHooks: LifecycleHook[];
+    destroyHooks: CleanupFn[];
+    updateHooks: LifecycleHook[];
+    refs: Map<string, Ref<any>>;
+    watchers: Array<{
+        stop: () => void;
+    }>;
+    isMounted: boolean;
+}
+/**
+ * Create a new component instance context.
+ * Called internally when a component script starts executing.
+ */
+export declare function createComponentInstance(element?: Element): ComponentInstance;
+/**
+ * Set the current component instance context.
+ */
+export declare function setCurrentInstance(instance: ComponentInstance | null): void;
+/**
+ * Get the current component instance context.
+ */
+export declare function getCurrentInstance(): ComponentInstance | null;
+/**
+ * Register a callback to run when the component is mounted to the DOM.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { onMount } from 'stx'
+ *
+ * onMount(() => {
+ *   console.log('Component mounted!')
+ *
+ *   // Return cleanup function (optional)
+ *   return () => {
+ *     console.log('Cleanup on unmount')
+ *   }
+ * })
+ * </script>
+ * ```
+ */
+export declare function onMount(hook: LifecycleHook): void;
+/**
+ * Register a callback to run when the component is destroyed/unmounted.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { onMount, onDestroy } from 'stx'
+ *
+ * onMount(() => {
+ *   const interval = setInterval(() => console.log('tick'), 1000)
+ *
+ *   onDestroy(() => {
+ *     clearInterval(interval)
+ *   })
+ * })
+ * </script>
+ * ```
+ */
+export declare function onDestroy(hook: CleanupFn): void;
+/**
+ * Register a callback to run when the component updates.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { onUpdate } from 'stx'
+ *
+ * onUpdate(() => {
+ *   console.log('Component updated!')
+ * })
+ * </script>
+ * ```
+ */
+export declare function onUpdate(hook: LifecycleHook): void;
+/**
+ * Alias for onMount - matches common naming conventions.
+ */
+export declare const onMounted: typeof onMount;
+/**
+ * Alias for onDestroy - matches Vue naming.
+ */
+export declare const onUnmounted: typeof onDestroy;
+/**
+ * Alias for onUpdate - matches Vue naming.
+ */
+export declare const onUpdated: typeof onUpdate;
+/**
+ * Create a ref for holding a DOM element reference.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { ref, onMount } from 'stx'
+ *
+ * const inputRef = ref<HTMLInputElement>()
+ *
+ * onMount(() => {
+ *   inputRef.value?.focus()
+ * })
+ * </script>
+ *
+ * <input type="text" @ref="inputRef" />
+ * ```
+ */
+export declare function ref<T = HTMLElement>(initialValue?: T | null): Ref<T>;
+/**
+ * Create a named ref that can be bound via @ref="name" in templates.
+ */
+export declare function namedRef<T = HTMLElement>(name: string, initialValue?: T | null): Ref<T>;
+/**
+ * Watch a reactive source and run a callback when it changes.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { watch } from 'stx'
+ * import { counterStore } from '@stores'
+ *
+ * watch(
+ *   () => counterStore.count,
+ *   (newVal, oldVal) => {
+ *     console.log(`Count changed: ${oldVal} → ${newVal}`)
+ *   }
+ * )
+ * </script>
+ * ```
+ */
+export declare function watch<T>(source: WatchSource<T>, callback: WatchCallback<T>, options?: {
+    immediate?: boolean;
+}): () => void;
+/**
+ * Create a computed value that updates when dependencies change.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { computed } from 'stx'
+ * import { counterStore } from '@stores'
+ *
+ * const doubleCount = computed(() => counterStore.count * 2)
+ *
+ * // Access value
+ * console.log(doubleCount.value)
+ * </script>
+ * ```
+ */
+export declare function computed<T>(getter: () => T): {
+    readonly value: T;
+};
+/**
+ * Initialize a component and run its setup.
+ * This is called by the STX runtime when a component is created.
+ */
+export declare function setupComponent(element: Element, setup: () => void): ComponentInstance;
+/**
+ * Mount a component instance - runs onMount hooks.
+ */
+export declare function mountComponent(instance: ComponentInstance): void;
+/**
+ * Update a component instance - runs onUpdate hooks.
+ */
+export declare function updateComponent(instance: ComponentInstance): void;
+/**
+ * Destroy a component instance - runs cleanup and onDestroy hooks.
+ */
+export declare function destroyComponent(instance: ComponentInstance): void;
+/**
+ * Generate the client-side runtime script for lifecycle management.
+ */
+export declare function generateLifecycleRuntime(): string;
+/** Symbol for injection keys */
+export type InjectionKey<T> = symbol & {
+    __type?: T;
+};
+/**
+ * Create a typed injection key.
+ *
+ * @example
+ * ```typescript
+ * const ThemeKey = createInjectionKey<{ mode: 'dark' | 'light' }>('theme')
+ * ```
+ */
+export declare function createInjectionKey<T>(description?: string): InjectionKey<T>;
+/**
+ * Provide a value that can be injected by descendant components.
+ *
+ * @example
+ * ```html
+ * <script server>
+ * import { provide } from 'stx'
+ *
+ * // Provide a theme object
+ * provide('theme', { mode: 'dark', accent: 'purple' })
+ *
+ * // Or with a typed key
+ * import { ThemeKey } from './injection-keys'
+ * provide(ThemeKey, { mode: 'dark', accent: 'purple' })
+ * </script>
+ * ```
+ */
+export declare function provide<T>(key: string | InjectionKey<T>, value: T): void;
+/**
+ * Inject a value provided by an ancestor component.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { inject } from 'stx'
+ *
+ * // Inject with default value
+ * const theme = inject('theme', { mode: 'light', accent: 'blue' })
+ *
+ * // Inject required value (throws if not provided)
+ * const auth = inject('auth')
+ * </script>
+ * ```
+ */
+export declare function inject<T>(key: string | InjectionKey<T>): T | undefined;
+export declare function inject<T>(key: string | InjectionKey<T>, defaultValue: T): T;
+/**
+ * Create a new injection scope.
+ * Called internally when entering a component.
+ */
+export declare function pushInjectionScope(): void;
+/**
+ * Exit the current injection scope.
+ * Called internally when leaving a component.
+ */
+export declare function popInjectionScope(): void;
+/**
+ * Run a function within a new injection scope.
+ * Useful for component rendering.
+ */
+export declare function withInjectionScope<T>(fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Clear all injections (for testing).
+ */
+export declare function clearInjections(): void;
+/** Built-in injection key for theme */
+export declare const ThemeKey: InjectionKey<{
+    mode: 'light' | 'dark';
+    accent?: string;
+}>;
+/** Built-in injection key for router */
+export declare const RouterKey: InjectionKey<{
+    currentRoute: string;
+    navigate: (path: string) => void;
+}>;
+/** Built-in injection key for i18n */
+export declare const I18nKey: InjectionKey<{
+    locale: string;
+    t: (key: string) => string;
+}>;
+export { ref as createRef };