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

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

@@ -0,0 +1,100 @@
+/**
+ * Track keyboard state
+ */
+export declare function useKeyboard(options?: KeyboardOptions): KeyboardRef;
+/**
+ * Register a hotkey handler
+ */
+export declare function useHotkey(hotkey: string | string[], callback: HotkeyCallback, options?: HotkeyOptions): () => void;
+/**
+ * Check if a specific key is currently pressed
+ */
+export declare function useKeyPressed(key: string, options?: KeyboardOptions): {
+  get: () => boolean
+  subscribe: (fn: (pressed: boolean) => void) => () => void
+};
+/**
+ * Detect key sequences (like Konami code)
+ */
+export declare function useKeySequence(sequence: string[], callback: () => void, options?: { timeout?: number; target?: Window | HTMLElement | Document | null }): () => void;
+/**
+ * Common keyboard shortcuts helper
+ */
+export declare const shortcuts: {
+  save: 'ctrl+s';
+  undo: 'ctrl+z';
+  redo: 'ctrl+shift+z';
+  copy: 'ctrl+c';
+  paste: 'ctrl+v';
+  cut: 'ctrl+x';
+  selectAll: 'ctrl+a';
+  find: 'ctrl+f';
+  replace: 'ctrl+h';
+  newTab: 'ctrl+t';
+  closeTab: 'ctrl+w';
+  refresh: 'ctrl+r';
+  escape: 'escape';
+  enter: 'enter';
+  saveMac: 'meta+s';
+  undoMac: 'meta+z';
+  redoMac: 'meta+shift+z';
+  copyMac: 'meta+c';
+  pasteMac: 'meta+v';
+  cutMac: 'meta+x'
+};
+/**
+ * useKeyboard - Reactive keyboard input tracking
+ *
+ * Track keyboard state, handle hotkeys, and manage keyboard shortcuts.
+ *
+ * @example
+ * ```ts
+ * // Track all keyboard state
+ * const keyboard = useKeyboard()
+ * keyboard.subscribe(state => {
+ *   if (state.ctrl && state.pressed.has('s')) {
+ *     console.log('Ctrl+S pressed!')
+ *   }
+ * })
+ *
+ * // Simple hotkey
+ * useHotkey('ctrl+s', (e) => {
+ *   e.preventDefault()
+ *   save()
+ * })
+ *
+ * // Check if specific key is pressed
+ * const isSpacePressed = useKeyPressed('Space')
+ * ```
+ */
+export declare interface KeyboardState {
+  pressed: Set<string>
+  lastKey: string | null
+  lastEvent: KeyboardEvent | null
+  ctrl: boolean
+  alt: boolean
+  shift: boolean
+  meta: boolean
+  timestamp: number
+}
+export declare interface KeyboardOptions {
+  target?: Window | HTMLElement | Document | null
+  capture?: boolean
+  passive?: boolean
+}
+export declare interface KeyboardRef {
+  get: () => KeyboardState
+  subscribe: (fn: (state: KeyboardState) => void) => () => void
+  isPressed: (key: string) => boolean
+  stop: () => void
+}
+export declare interface HotkeyOptions {
+  target?: Window | HTMLElement | Document | null
+  preventDefault?: boolean
+  stopPropagation?: boolean
+  ignoreRepeat?: boolean
+  keyup?: boolean
+  ignoreInputs?: boolean
+}
+// eslint-disable-next-line pickier/no-unused-vars
+declare type HotkeyCallback = (event: KeyboardEvent) => void;

package/dist/composables/use-keyboard.js

@@ -0,0 +1,224 @@
+function parseHotkey(hotkey) {
+  const parts = hotkey.toLowerCase().split("+").map((p) => p.trim());
+  return {
+    key: parts[parts.length - 1],
+    ctrl: parts.includes("ctrl") || parts.includes("control"),
+    alt: parts.includes("alt") || parts.includes("option"),
+    shift: parts.includes("shift"),
+    meta: parts.includes("meta") || parts.includes("cmd") || parts.includes("command") || parts.includes("win")
+  };
+}
+function matchesHotkey(event, hotkey) {
+  const eventKey = event.key.toLowerCase(), eventCode = event.code.toLowerCase();
+  return (eventKey === hotkey.key || eventCode === hotkey.key || eventCode === `key${hotkey.key}` || eventCode === `digit${hotkey.key}` || hotkey.key === "space" && event.code === "Space" || hotkey.key === "enter" && event.key === "Enter" || hotkey.key === "escape" && event.key === "Escape" || hotkey.key === "esc" && event.key === "Escape" || hotkey.key === "tab" && event.key === "Tab" || hotkey.key === "backspace" && event.key === "Backspace" || hotkey.key === "delete" && event.key === "Delete" || hotkey.key === "up" && event.key === "ArrowUp" || hotkey.key === "down" && event.key === "ArrowDown" || hotkey.key === "left" && event.key === "ArrowLeft" || hotkey.key === "right" && event.key === "ArrowRight") && event.ctrlKey === hotkey.ctrl && event.altKey === hotkey.alt && event.shiftKey === hotkey.shift && event.metaKey === hotkey.meta;
+}
+function isInputFocused() {
+  const active = document.activeElement;
+  if (!active)
+    return !1;
+  const tagName = active.tagName.toLowerCase();
+  return tagName === "input" || tagName === "textarea" || tagName === "select" || active.isContentEditable;
+}
+export function useKeyboard(options = {}) {
+  const {
+    target = typeof window < "u" ? window : null,
+    capture = !1,
+    passive = !0
+  } = options;
+  let state = {
+    pressed: new Set,
+    lastKey: null,
+    lastEvent: null,
+    ctrl: !1,
+    alt: !1,
+    shift: !1,
+    meta: !1,
+    timestamp: 0
+  }, listeners = [], cleanup = null;
+  const notify = () => {
+    listeners.forEach((fn) => fn(state));
+  }, handleKeyDown = (e) => {
+    const newPressed = new Set(state.pressed);
+    newPressed.add(e.key.toLowerCase());
+    newPressed.add(e.code.toLowerCase());
+    state = {
+      pressed: newPressed,
+      lastKey: e.key,
+      lastEvent: e,
+      ctrl: e.ctrlKey,
+      alt: e.altKey,
+      shift: e.shiftKey,
+      meta: e.metaKey,
+      timestamp: Date.now()
+    };
+    notify();
+  }, handleKeyUp = (e) => {
+    const newPressed = new Set(state.pressed);
+    newPressed.delete(e.key.toLowerCase());
+    newPressed.delete(e.code.toLowerCase());
+    state = {
+      pressed: newPressed,
+      lastKey: e.key,
+      lastEvent: e,
+      ctrl: e.ctrlKey,
+      alt: e.altKey,
+      shift: e.shiftKey,
+      meta: e.metaKey,
+      timestamp: Date.now()
+    };
+    notify();
+  }, handleBlur = () => {
+    state = {
+      ...state,
+      pressed: new Set,
+      ctrl: !1,
+      alt: !1,
+      shift: !1,
+      meta: !1
+    };
+    notify();
+  }, setupListeners = () => {
+    if (!target)
+      return;
+    const t = target, opts = { capture, passive };
+    t.addEventListener("keydown", handleKeyDown, opts);
+    t.addEventListener("keyup", handleKeyUp, opts);
+    if (typeof window < "u")
+      window.addEventListener("blur", handleBlur);
+    cleanup = () => {
+      t.removeEventListener("keydown", handleKeyDown, opts);
+      t.removeEventListener("keyup", handleKeyUp, opts);
+      if (typeof window < "u")
+        window.removeEventListener("blur", handleBlur);
+    };
+  };
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      if (listeners.length === 0)
+        setupListeners();
+      listeners.push(fn);
+      fn(state);
+      return () => {
+        listeners = listeners.filter((l) => l !== fn);
+        if (listeners.length === 0 && cleanup) {
+          cleanup();
+          cleanup = null;
+        }
+      };
+    },
+    isPressed: (key) => {
+      const k = key.toLowerCase();
+      return state.pressed.has(k);
+    },
+    stop: () => {
+      if (cleanup) {
+        cleanup();
+        cleanup = null;
+      }
+      listeners = [];
+    }
+  };
+}
+export function useHotkey(hotkey, callback, options = {}) {
+  const {
+    target = typeof window < "u" ? window : null,
+    preventDefault = !0,
+    stopPropagation = !1,
+    ignoreRepeat = !0,
+    keyup = !1,
+    ignoreInputs = !0
+  } = options;
+  if (!target)
+    return () => {};
+  const parsedHotkeys = (Array.isArray(hotkey) ? hotkey : [hotkey]).map(parseHotkey), handler = (e) => {
+    if (ignoreRepeat && e.repeat)
+      return;
+    if (ignoreInputs && isInputFocused())
+      return;
+    if (!parsedHotkeys.some((hk) => matchesHotkey(e, hk)))
+      return;
+    if (preventDefault)
+      e.preventDefault();
+    if (stopPropagation)
+      e.stopPropagation();
+    callback(e);
+  }, eventType = keyup ? "keyup" : "keydown", t = target;
+  t.addEventListener(eventType, handler);
+  return () => {
+    t.removeEventListener(eventType, handler);
+  };
+}
+export function useKeyPressed(key, options = {}) {
+  const keyboard = useKeyboard(options), targetKey = key.toLowerCase();
+  let listeners = [], lastValue = !1, unsubKeyboard = null;
+  return {
+    get: () => keyboard.isPressed(targetKey),
+    subscribe: (fn) => {
+      if (listeners.length === 0)
+        unsubKeyboard = keyboard.subscribe((state) => {
+          const isPressed = state.pressed.has(targetKey);
+          if (isPressed !== lastValue) {
+            lastValue = isPressed;
+            listeners.forEach((l) => l(isPressed));
+          }
+        });
+      listeners.push(fn);
+      fn(keyboard.isPressed(targetKey));
+      return () => {
+        listeners = listeners.filter((l) => l !== fn);
+        if (listeners.length === 0 && unsubKeyboard) {
+          unsubKeyboard();
+          unsubKeyboard = null;
+        }
+      };
+    }
+  };
+}
+export function useKeySequence(sequence, callback, options = {}) {
+  const { timeout = 1000, target = typeof window < "u" ? window : null } = options;
+  if (!target)
+    return () => {};
+  let buffer = [], lastTime = 0;
+  const handler = (e) => {
+    const now = Date.now();
+    if (now - lastTime > timeout)
+      buffer = [];
+    lastTime = now;
+    buffer.push(e.key.toLowerCase());
+    if (buffer.length > sequence.length)
+      buffer = buffer.slice(-sequence.length);
+    if (buffer.length === sequence.length) {
+      if (buffer.every((key, i) => key === sequence[i].toLowerCase())) {
+        callback();
+        buffer = [];
+      }
+    }
+  }, t = target;
+  t.addEventListener("keydown", handler);
+  return () => {
+    t.removeEventListener("keydown", handler);
+  };
+}
+export const shortcuts = {
+  save: "ctrl+s",
+  undo: "ctrl+z",
+  redo: "ctrl+shift+z",
+  copy: "ctrl+c",
+  paste: "ctrl+v",
+  cut: "ctrl+x",
+  selectAll: "ctrl+a",
+  find: "ctrl+f",
+  replace: "ctrl+h",
+  newTab: "ctrl+t",
+  closeTab: "ctrl+w",
+  refresh: "ctrl+r",
+  escape: "escape",
+  enter: "enter",
+  saveMac: "meta+s",
+  undoMac: "meta+z",
+  redoMac: "meta+shift+z",
+  copyMac: "meta+c",
+  pasteMac: "meta+v",
+  cutMac: "meta+x"
+};

package/dist/composables/use-media-query.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Create a reactive media query
+ *
+ * @example
+ * ```ts
+ * const isDark = useMediaQuery('(prefers-color-scheme: dark)')
+ * const isMobile = useMediaQuery('(max-width: 768px)')
+ *
+ * isDark.subscribe((matches) => {
+ *   console.log('Dark mode:', matches)
+ * })
+ * ```
+ */
+export declare function useMediaQuery(query: string): MediaQueryRef;
+/**
+ * Reactive dark mode preference
+ */
+export declare function usePreferredDark(): MediaQueryRef;
+/**
+ * Reactive light mode preference
+ */
+export declare function usePreferredLight(): MediaQueryRef;
+/**
+ * Reactive reduced motion preference
+ */
+export declare function usePreferredReducedMotion(): MediaQueryRef;
+/**
+ * Reactive contrast preference
+ */
+export declare function usePreferredContrast(): MediaQueryRef;
+/**
+ * Reactive breakpoint helpers
+ */
+export declare function useBreakpoint(breakpoint: keyof typeof breakpoints): MediaQueryRef;
+export declare function useIsMobile(): MediaQueryRef;
+export declare function useIsTablet(): MediaQueryRef;
+export declare function useIsDesktop(): MediaQueryRef;
+/**
+ * Common breakpoints
+ */
+export declare const breakpoints: {
+  sm: '(min-width: 640px)';
+  md: '(min-width: 768px)';
+  lg: '(min-width: 1024px)';
+  xl: '(min-width: 1280px)';
+  '2xl': '(min-width: 1536px)'
+};
+/**
+ * useMediaQuery - Reactive media query composable
+ *
+ * Provides reactive tracking of CSS media queries.
+ */
+export declare interface MediaQueryRef {
+  matches: boolean
+  subscribe: (callback: (matches: boolean) => void) => () => void
+}

package/dist/composables/use-media-query.js

@@ -0,0 +1,62 @@
+export function useMediaQuery(query) {
+  const subscribers = new Set, isClient = typeof window < "u";
+  let mediaQuery = null, currentMatches = !1;
+  if (isClient) {
+    mediaQuery = window.matchMedia(query);
+    currentMatches = mediaQuery.matches;
+    const handler = (event) => {
+      currentMatches = event.matches;
+      for (const callback of subscribers)
+        try {
+          callback(event.matches);
+        } catch (e) {
+          console.error("[useMediaQuery] Subscriber error:", e);
+        }
+    };
+    if (mediaQuery.addEventListener)
+      mediaQuery.addEventListener("change", handler);
+    else
+      mediaQuery.addListener(handler);
+  }
+  return {
+    get matches() {
+      return currentMatches;
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      callback(currentMatches);
+      return () => subscribers.delete(callback);
+    }
+  };
+}
+export function usePreferredDark() {
+  return useMediaQuery("(prefers-color-scheme: dark)");
+}
+export function usePreferredLight() {
+  return useMediaQuery("(prefers-color-scheme: light)");
+}
+export function usePreferredReducedMotion() {
+  return useMediaQuery("(prefers-reduced-motion: reduce)");
+}
+export function usePreferredContrast() {
+  return useMediaQuery("(prefers-contrast: more)");
+}
+export const breakpoints = {
+  sm: "(min-width: 640px)",
+  md: "(min-width: 768px)",
+  lg: "(min-width: 1024px)",
+  xl: "(min-width: 1280px)",
+  "2xl": "(min-width: 1536px)"
+};
+export function useBreakpoint(breakpoint) {
+  return useMediaQuery(breakpoints[breakpoint]);
+}
+export function useIsMobile() {
+  return useMediaQuery("(max-width: 767px)");
+}
+export function useIsTablet() {
+  return useMediaQuery("(min-width: 768px) and (max-width: 1023px)");
+}
+export function useIsDesktop() {
+  return useMediaQuery("(min-width: 1024px)");
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Reactive meta tag management.
+ *
+ * @example
+ * ```ts
+ * const meta = useMeta({
+ *   title: 'My Page',
+ *   description: 'A page description',
+ *   og: { image: 'https://example.com/og.png' }
+ * })
+ *
+ * // Dynamic updates
+ * meta.setTitle('New Title')
+ * meta.setMeta('description', 'Updated description')
+ * meta.setOgMeta('image', 'https://example.com/new.png')
+ * ```
+ */
+export declare function useMeta(options?: UseMetaOptions): MetaRef;
+/**
+ * useMeta - Reactive meta tag management composable
+ *
+ * Provides clean APIs for managing `<meta>` tags without raw `document.querySelector`.
+ */
+export declare interface UseMetaOptions {
+  title?: string
+  description?: string
+  meta?: Record<string, string>
+  og?: Record<string, string>
+}
+export declare interface MetaRef {
+  setMeta: (name: string, content: string) => void
+  setOgMeta: (property: string, content: string) => void
+  removeMeta: (name: string) => void
+  setTitle: (title: string) => void
+}

package/dist/composables/use-meta.js

@@ -0,0 +1,48 @@
+export function useMeta(options) {
+  if (typeof document > "u")
+    return {
+      setMeta: () => {},
+      setOgMeta: () => {},
+      removeMeta: () => {},
+      setTitle: () => {}
+    };
+  function findOrCreateMeta(attr, key) {
+    let el = document.querySelector(`meta[${attr}="${key}"]`);
+    if (!el) {
+      el = document.createElement("meta");
+      el.setAttribute(attr, key);
+      document.head.appendChild(el);
+    }
+    return el;
+  }
+  const ref = {
+    setMeta(name, content) {
+      findOrCreateMeta("name", name).setAttribute("content", content);
+    },
+    setOgMeta(property, content) {
+      const key = property.startsWith("og:") ? property : `og:${property}`;
+      findOrCreateMeta("property", key).setAttribute("content", content);
+    },
+    removeMeta(name) {
+      const el = document.querySelector(`meta[name="${name}"]`);
+      if (el)
+        el.remove();
+    },
+    setTitle(title) {
+      document.title = title;
+    }
+  };
+  if (options) {
+    if (options.title)
+      ref.setTitle(options.title);
+    if (options.description)
+      ref.setMeta("description", options.description);
+    if (options.meta)
+      for (const [name, content] of Object.entries(options.meta))
+        ref.setMeta(name, content);
+    if (options.og)
+      for (const [property, content] of Object.entries(options.og))
+        ref.setOgMeta(property, content);
+  }
+  return ref;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Track mouse position globally or within a target
+ */
+export declare function useMouse(options?: MouseOptions): MouseRef;
+/**
+ * Track mouse position relative to an element
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function useMouseInElement(element: HTMLElement | (() => HTMLElement | null) | null, options?: Omit<MouseOptions, 'target'>): ElementMouseRef;
+/**
+ * Track pointer (unified mouse + touch + pen)
+ */
+export declare function usePointer(options?: MouseOptions): MouseRef;
+/**
+ * useMouse - Reactive mouse/pointer position tracking
+ *
+ * Track mouse position, movement, and button states.
+ *
+ * @example
+ * ```ts
+ * const mouse = useMouse()
+ * mouse.subscribe(state => {
+ *   console.log(`Mouse at ${state.x}, ${state.y}`)
+ * })
+ *
+ * // Track within a specific element
+ * const elementMouse = useMouseInElement(myElement)
+ * ```
+ */
+export declare interface MouseState {
+  x: number
+  y: number
+  pageX: number
+  pageY: number
+  clientX: number
+  clientY: number
+  movementX: number
+  movementY: number
+  buttons: number
+  isPressed: boolean
+  isInside: boolean
+}
+export declare interface MouseOptions {
+  target?: Window | HTMLElement | null
+  touch?: boolean
+  resetOnLeave?: boolean
+  type?: 'page' | 'client' | 'screen' | 'movement'
+}
+export declare interface MouseRef {
+  get: () => MouseState
+  subscribe: (fn: (state: MouseState) => void) => () => void
+  stop: () => void
+}
+export declare interface ElementMouseState extends MouseState {
+  elementX: number
+  elementY: number
+  elementWidth: number
+  elementHeight: number
+  isOutside: boolean
+}
+export declare interface ElementMouseRef {
+  get: () => ElementMouseState
+  subscribe: (fn: (state: ElementMouseState) => void) => () => void
+  stop: () => void
+}