@xaui/native 0.0.21 → 0.0.24

package/dist/feature-discovery/index.cjs

@@ -0,0 +1,531 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/components/feature-discovery/index.ts
+var feature_discovery_exports = {};
+__export(feature_discovery_exports, {
+  FeatureDiscovery: () => FeatureDiscovery
+});
+module.exports = __toCommonJS(feature_discovery_exports);
+
+// src/components/feature-discovery/feature-discovery.tsx
+var import_react7 = __toESM(require("react"), 1);
+var import_react_native6 = require("react-native");
+var import_core3 = require("@xaui/core");
+
+// src/components/feature-discovery/feature-discovery.style.ts
+var import_react_native = require("react-native");
+var styles = import_react_native.StyleSheet.create({
+  root: {
+    flex: 1
+  },
+  absoluteFill: {
+    ...import_react_native.StyleSheet.absoluteFillObject
+  },
+  circle: {
+    position: "absolute"
+  },
+  spotlightHalo: {
+    position: "absolute",
+    borderWidth: 1,
+    borderColor: "rgba(255, 255, 255, 0.35)"
+  },
+  highlightContainer: {
+    position: "absolute",
+    alignItems: "center",
+    justifyContent: "center"
+  },
+  messageContainer: {
+    position: "absolute",
+    gap: 10,
+    paddingVertical: 16,
+    paddingHorizontal: 16,
+    borderRadius: 12
+  },
+  messageHeader: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    justifyContent: "space-between",
+    gap: 8
+  },
+  messageTitleWrapper: {
+    flex: 1
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: "700"
+  },
+  closeButton: {
+    padding: 4
+  },
+  closeIcon: {
+    fontSize: 18,
+    fontWeight: "600"
+  },
+  description: {
+    fontSize: 16,
+    fontWeight: "400",
+    opacity: 0.86,
+    lineHeight: 22
+  },
+  actionPressable: {
+    alignSelf: "flex-start"
+  },
+  actionText: {
+    fontSize: 14,
+    fontWeight: "600",
+    textDecorationLine: "underline"
+  }
+});
+
+// src/components/feature-discovery/feature-discovery.hook.ts
+var import_react6 = require("react");
+var import_react_native5 = require("react-native");
+var import_core = require("@xaui/core");
+
+// src/core/theme-context.tsx
+var import_react4 = __toESM(require("react"), 1);
+var import_react_native3 = require("react-native");
+var import_theme = require("@xaui/core/theme");
+var import_palette = require("@xaui/core/palette");
+
+// src/core/portal/portal.tsx
+var import_react2 = require("react");
+
+// src/core/portal/portal-context.ts
+var import_react = require("react");
+var PortalContext = (0, import_react.createContext)(null);
+
+// src/core/portal/portal-host.tsx
+var import_react3 = __toESM(require("react"), 1);
+var import_react_native2 = require("react-native");
+var hostStyles = import_react_native2.StyleSheet.create({
+  container: {
+    flex: 1
+  }
+});
+
+// src/core/theme-context.tsx
+var XUIThemeContext = (0, import_react4.createContext)(null);
+
+// src/core/theme-hooks.ts
+var import_react5 = require("react");
+var import_react_native4 = require("react-native");
+function useXUITheme() {
+  const theme = (0, import_react5.useContext)(XUIThemeContext);
+  if (!theme) {
+    throw new Error("useXUITheme must be used within XUIProvider");
+  }
+  return theme;
+}
+
+// src/core/index.ts
+var import_theme2 = require("@xaui/core/theme");
+
+// src/components/feature-discovery/feature-discovery.hook.ts
+var useFeatureDiscoveryAnimations = () => {
+  const backdropOpacity = (0, import_react6.useRef)(new import_react_native5.Animated.Value(0)).current;
+  const circleAnimScale = (0, import_react6.useRef)(new import_react_native5.Animated.Value(0.2)).current;
+  const contentOpacity = (0, import_react6.useRef)(new import_react_native5.Animated.Value(0)).current;
+  const haloScale = (0, import_react6.useRef)(new import_react_native5.Animated.Value(0.8)).current;
+  const startAnimations = (0, import_react6.useCallback)(() => {
+    import_react_native5.Animated.parallel([
+      import_react_native5.Animated.timing(backdropOpacity, {
+        toValue: 1,
+        duration: 220,
+        useNativeDriver: true
+      }),
+      import_react_native5.Animated.spring(circleAnimScale, {
+        toValue: 1,
+        friction: 8,
+        tension: 80,
+        useNativeDriver: true
+      }),
+      import_react_native5.Animated.timing(contentOpacity, {
+        toValue: 1,
+        duration: 260,
+        useNativeDriver: true
+      }),
+      import_react_native5.Animated.spring(haloScale, {
+        toValue: 1,
+        friction: 8,
+        tension: 80,
+        useNativeDriver: true
+      })
+    ]).start();
+  }, [backdropOpacity, circleAnimScale, contentOpacity, haloScale]);
+  const resetAnimations = (0, import_react6.useCallback)(() => {
+    backdropOpacity.setValue(0);
+    circleAnimScale.setValue(0.2);
+    contentOpacity.setValue(0);
+    haloScale.setValue(0.8);
+  }, [backdropOpacity, circleAnimScale, contentOpacity, haloScale]);
+  return {
+    backdropOpacity,
+    circleAnimScale,
+    contentOpacity,
+    haloScale,
+    startAnimations,
+    resetAnimations
+  };
+};
+var useFeatureDiscoveryLayout = (targetRef) => {
+  const { width: viewportWidth, height: viewportHeight } = (0, import_react_native5.useWindowDimensions)();
+  const [targetLayout, setTargetLayout] = (0, import_react6.useState)(null);
+  const measureTarget = (0, import_react6.useCallback)(() => {
+    targetRef.current?.measureInWindow((x, y, width, height) => {
+      if (!width && !height) {
+        setTargetLayout({
+          x: viewportWidth / 2 - 28,
+          y: viewportHeight / 2 - 28,
+          width: 56,
+          height: 56
+        });
+        return;
+      }
+      setTargetLayout({ x, y, width, height });
+    });
+  }, [targetRef, viewportHeight, viewportWidth]);
+  const fallbackTarget = (0, import_react6.useMemo)(
+    () => ({
+      x: viewportWidth / 2 - 28,
+      y: viewportHeight / 2 - 28,
+      width: 56,
+      height: 56
+    }),
+    [viewportWidth, viewportHeight]
+  );
+  const target = targetLayout ?? fallbackTarget;
+  return {
+    targetLayout,
+    target,
+    measureTarget,
+    setTargetLayout,
+    viewportWidth,
+    viewportHeight
+  };
+};
+var useFeatureDiscoveryGeometry = (target, viewportWidth, viewportHeight, spotlightPadding, circleScale) => {
+  const HIGHLIGHT_EDGE_INSET = 16;
+  const maxTargetX = Math.max(
+    HIGHLIGHT_EDGE_INSET,
+    viewportWidth - target.width - HIGHLIGHT_EDGE_INSET
+  );
+  const maxTargetY = Math.max(
+    HIGHLIGHT_EDGE_INSET,
+    viewportHeight - target.height - HIGHLIGHT_EDGE_INSET
+  );
+  const clampedTargetX = Math.min(
+    Math.max(target.x, HIGHLIGHT_EDGE_INSET),
+    maxTargetX
+  );
+  const clampedTargetY = Math.min(
+    Math.max(target.y, HIGHLIGHT_EDGE_INSET),
+    maxTargetY
+  );
+  const targetCenterX = clampedTargetX + target.width / 2;
+  const targetCenterY = clampedTargetY + target.height / 2;
+  const spotlightSize = Math.max(target.width, target.height) + spotlightPadding * 2;
+  const circleDiameter = (0, import_react6.useMemo)(() => {
+    return viewportWidth * circleScale;
+  }, [circleScale, viewportWidth]);
+  const circleRadius = circleDiameter / 2;
+  const TEXT_PADDING = 24;
+  const TARGET_GAP = 30;
+  const MIN_MESSAGE_HEIGHT = 140;
+  const MIN_MESSAGE_WIDTH = 280;
+  const MESSAGE_VERTICAL_OFFSET = 14;
+  const isTargetInTopHalf = targetCenterY < viewportHeight * 0.55;
+  const baseMessageTop = isTargetInTopHalf ? Math.min(viewportHeight - 200, clampedTargetY + target.height + TARGET_GAP) : Math.max(TEXT_PADDING, clampedTargetY - 150);
+  const messageTop = Math.max(TEXT_PADDING, baseMessageTop - MESSAGE_VERTICAL_OFFSET);
+  const textDy = messageTop - targetCenterY;
+  const textHalfChord = Math.abs(textDy) < circleRadius ? Math.sqrt(circleRadius ** 2 - textDy ** 2) : 0;
+  const baseMsgLeft = Math.max(
+    TEXT_PADDING,
+    targetCenterX - textHalfChord + TEXT_PADDING
+  );
+  const baseMsgRight = Math.max(
+    TEXT_PADDING,
+    viewportWidth - (targetCenterX + textHalfChord - TEXT_PADDING)
+  );
+  const baseMsgWidth = viewportWidth - baseMsgLeft - baseMsgRight;
+  const clampedMinMessageWidth = Math.min(
+    MIN_MESSAGE_WIDTH,
+    viewportWidth - TEXT_PADDING * 2
+  );
+  const isTargetOnLeft = targetCenterX < viewportWidth / 2;
+  const shouldUseSideAnchoredLayout = baseMsgWidth < clampedMinMessageWidth;
+  const msgLeft = shouldUseSideAnchoredLayout ? isTargetOnLeft ? TEXT_PADDING : viewportWidth - TEXT_PADDING - clampedMinMessageWidth : baseMsgLeft;
+  const msgRight = shouldUseSideAnchoredLayout ? isTargetOnLeft ? viewportWidth - TEXT_PADDING - clampedMinMessageWidth : TEXT_PADDING : baseMsgRight;
+  const circleBottomY = targetCenterY + circleRadius - TEXT_PADDING;
+  const msgMaxHeight = Math.max(MIN_MESSAGE_HEIGHT, circleBottomY - messageTop);
+  return {
+    targetCenterX,
+    targetCenterY,
+    spotlightSize,
+    circleDiameter,
+    circleRadius,
+    messageTop,
+    msgLeft,
+    msgRight,
+    msgMaxHeight,
+    isTargetOnLeft,
+    highlightX: clampedTargetX,
+    highlightY: clampedTargetY
+  };
+};
+var useFeatureDiscoveryTheme = (themeColor, overlayColor) => {
+  const theme = useXUITheme();
+  const colorScheme = theme.colors[(0, import_core.getSafeThemeColor)(themeColor)];
+  const resolvedOverlayColor = (0, import_react6.useMemo)(
+    () => overlayColor ?? (0, import_core.withOpacity)(theme.colors.foreground, 0.42),
+    [overlayColor, theme.colors.foreground]
+  );
+  return {
+    colorScheme,
+    resolvedOverlayColor
+  };
+};
+
+// src/components/feature-discovery/feature-discovery.tsx
+var DEFAULT_SPOTLIGHT_PADDING = 14;
+var DEFAULT_CIRCLE_SCALE = 1.65;
+var FeatureDiscovery = ({
+  isVisible,
+  targetRef,
+  title,
+  description,
+  actionText,
+  onActionPress,
+  onDismiss,
+  dismissOnBackdropPress = true,
+  themeColor = "primary",
+  overlayColor,
+  spotlightPadding = DEFAULT_SPOTLIGHT_PADDING,
+  circleScale = DEFAULT_CIRCLE_SCALE,
+  highlightContent,
+  customAppearance
+}) => {
+  const {
+    backdropOpacity,
+    circleAnimScale,
+    contentOpacity,
+    haloScale,
+    startAnimations,
+    resetAnimations
+  } = useFeatureDiscoveryAnimations();
+  const { target, measureTarget, setTargetLayout, viewportWidth, viewportHeight } = useFeatureDiscoveryLayout(targetRef);
+  const {
+    targetCenterX,
+    targetCenterY,
+    spotlightSize,
+    circleDiameter,
+    messageTop,
+    msgLeft,
+    msgRight,
+    msgMaxHeight,
+    isTargetOnLeft,
+    highlightX,
+    highlightY
+  } = useFeatureDiscoveryGeometry(
+    target,
+    viewportWidth,
+    viewportHeight,
+    spotlightPadding,
+    circleScale
+  );
+  const { colorScheme, resolvedOverlayColor } = useFeatureDiscoveryTheme(
+    themeColor,
+    overlayColor
+  );
+  (0, import_react7.useEffect)(() => {
+    if (!isVisible) {
+      setTargetLayout(null);
+      return;
+    }
+    resetAnimations();
+    const timer = setTimeout(() => {
+      measureTarget();
+      startAnimations();
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [isVisible, measureTarget, resetAnimations, setTargetLayout, startAnimations]);
+  if (!isVisible) return null;
+  const renderContent = (content, textStyle) => {
+    if (typeof content === "string" || typeof content === "number") {
+      return /* @__PURE__ */ import_react7.default.createElement(import_react_native6.Text, { style: textStyle }, content);
+    }
+    return content;
+  };
+  return /* @__PURE__ */ import_react7.default.createElement(
+    import_react_native6.Modal,
+    {
+      visible: isVisible,
+      transparent: true,
+      animationType: "none",
+      statusBarTranslucent: true,
+      onRequestClose: onDismiss
+    },
+    /* @__PURE__ */ import_react7.default.createElement(
+      import_react_native6.View,
+      {
+        style: [styles.root, customAppearance?.root, customAppearance?.container]
+      },
+      /* @__PURE__ */ import_react7.default.createElement(
+        import_react_native6.Pressable,
+        {
+          style: styles.absoluteFill,
+          onPress: dismissOnBackdropPress ? onDismiss : void 0
+        },
+        /* @__PURE__ */ import_react7.default.createElement(
+          import_react_native6.Animated.View,
+          {
+            style: [
+              styles.absoluteFill,
+              {
+                backgroundColor: resolvedOverlayColor,
+                opacity: backdropOpacity
+              }
+            ]
+          }
+        )
+      ),
+      /* @__PURE__ */ import_react7.default.createElement(
+        import_react_native6.Animated.View,
+        {
+          style: [
+            styles.circle,
+            {
+              width: circleDiameter,
+              height: circleDiameter,
+              borderRadius: circleDiameter / 2,
+              left: targetCenterX - circleDiameter / 2,
+              top: targetCenterY - circleDiameter / 2,
+              backgroundColor: colorScheme.main,
+              opacity: contentOpacity,
+              transform: [{ scale: circleAnimScale }]
+            }
+          ]
+        }
+      ),
+      /* @__PURE__ */ import_react7.default.createElement(
+        import_react_native6.Animated.View,
+        {
+          style: [
+            styles.spotlightHalo,
+            {
+              width: spotlightSize,
+              height: spotlightSize,
+              borderRadius: spotlightSize / 2,
+              left: targetCenterX - spotlightSize / 2,
+              top: targetCenterY - spotlightSize / 2,
+              opacity: contentOpacity,
+              transform: [{ scale: haloScale }]
+            }
+          ]
+        }
+      ),
+      highlightContent && /* @__PURE__ */ import_react7.default.createElement(
+        import_react_native6.Animated.View,
+        {
+          style: [
+            styles.highlightContainer,
+            {
+              left: highlightX,
+              top: highlightY,
+              width: target.width,
+              height: target.height,
+              opacity: contentOpacity
+            },
+            customAppearance?.highlightContainer
+          ],
+          pointerEvents: "none"
+        },
+        highlightContent
+      ),
+      /* @__PURE__ */ import_react7.default.createElement(
+        import_react_native6.Animated.View,
+        {
+          style: [
+            styles.messageContainer,
+            {
+              top: messageTop,
+              left: msgLeft,
+              right: msgRight,
+              maxHeight: msgMaxHeight,
+              opacity: contentOpacity
+            },
+            customAppearance?.messageContainer
+          ],
+          pointerEvents: "box-none"
+        },
+        /* @__PURE__ */ import_react7.default.createElement(import_react_native6.View, { style: styles.messageHeader }, /* @__PURE__ */ import_react7.default.createElement(import_react_native6.View, { style: styles.messageTitleWrapper }, renderContent(title, [
+          styles.title,
+          { color: colorScheme.foreground },
+          { textAlign: isTargetOnLeft ? "left" : "right" },
+          customAppearance?.title
+        ])), /* @__PURE__ */ import_react7.default.createElement(
+          import_react_native6.Pressable,
+          {
+            onPress: onDismiss,
+            style: styles.closeButton,
+            accessibilityRole: "button"
+          },
+          /* @__PURE__ */ import_react7.default.createElement(import_react_native6.Text, { style: [styles.closeIcon, { color: colorScheme.foreground }] }, "\u2715")
+        )),
+        description ? renderContent(description, [
+          styles.description,
+          { color: (0, import_core3.withOpacity)(colorScheme.foreground, 0.9) },
+          { textAlign: isTargetOnLeft ? "left" : "right" },
+          customAppearance?.description
+        ]) : null,
+        actionText ? /* @__PURE__ */ import_react7.default.createElement(
+          import_react_native6.Pressable,
+          {
+            onPress: onActionPress,
+            style: [
+              styles.actionPressable,
+              { alignSelf: isTargetOnLeft ? "flex-start" : "flex-end" }
+            ],
+            accessibilityRole: "button"
+          },
+          renderContent(actionText, [
+            styles.actionText,
+            { color: colorScheme.foreground },
+            customAppearance?.actionText
+          ])
+        ) : null
+      )
+    )
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FeatureDiscovery
+});

package/dist/feature-discovery/index.d.cts

@@ -0,0 +1,82 @@
+import React, { RefObject, ReactNode } from 'react';
+import { ViewStyle, TextStyle } from 'react-native';
+import { T as ThemeColor } from '../index-BOw6tbkc.cjs';
+
+type MeasurableNode = {
+    measureInWindow: (callback: (x: number, y: number, width: number, height: number) => void) => void;
+};
+type FeatureDiscoveryCustomAppearance = {
+    root?: ViewStyle;
+    container?: ViewStyle;
+    title?: TextStyle;
+    description?: TextStyle;
+    actionText?: TextStyle;
+    highlightContainer?: ViewStyle;
+    messageContainer?: ViewStyle;
+};
+type FeatureDiscoveryProps = {
+    /**
+     * Whether the discovery overlay is visible.
+     */
+    isVisible: boolean;
+    /**
+     * Ref to the target element to highlight.
+     */
+    targetRef: RefObject<MeasurableNode | null>;
+    /**
+     * Discovery title.
+     */
+    title: ReactNode;
+    /**
+     * Optional discovery description.
+     */
+    description?: ReactNode;
+    /**
+     * Optional action label displayed under the text.
+     */
+    actionText?: ReactNode;
+    /**
+     * Called when action text is pressed.
+     */
+    onActionPress?: () => void;
+    /**
+     * Called when overlay should close.
+     */
+    onDismiss?: () => void;
+    /**
+     * Whether tapping outside dismisses the overlay.
+     * @default true
+     */
+    dismissOnBackdropPress?: boolean;
+    /**
+     * Accent color for the discovery circle.
+     * @default 'primary'
+     */
+    themeColor?: ThemeColor;
+    /**
+     * Backdrop color.
+     */
+    overlayColor?: string;
+    /**
+     * Extra spacing around target highlight.
+     * @default 14
+     */
+    spotlightPadding?: number;
+    /**
+     * Scale multiplier for discovery circle diameter.
+     * @default 1.65
+     */
+    circleScale?: number;
+    /**
+     * Optional custom content rendered over the highlighted target.
+     */
+    highlightContent?: ReactNode;
+    /**
+     * Optional style overrides.
+     */
+    customAppearance?: FeatureDiscoveryCustomAppearance;
+};
+
+declare const FeatureDiscovery: React.FC<FeatureDiscoveryProps>;
+
+export { FeatureDiscovery, type FeatureDiscoveryCustomAppearance, type FeatureDiscoveryProps };

package/dist/feature-discovery/index.d.ts

@@ -0,0 +1,82 @@
+import React, { RefObject, ReactNode } from 'react';
+import { ViewStyle, TextStyle } from 'react-native';
+import { T as ThemeColor } from '../index-BOw6tbkc.js';
+
+type MeasurableNode = {
+    measureInWindow: (callback: (x: number, y: number, width: number, height: number) => void) => void;
+};
+type FeatureDiscoveryCustomAppearance = {
+    root?: ViewStyle;
+    container?: ViewStyle;
+    title?: TextStyle;
+    description?: TextStyle;
+    actionText?: TextStyle;
+    highlightContainer?: ViewStyle;
+    messageContainer?: ViewStyle;
+};
+type FeatureDiscoveryProps = {
+    /**
+     * Whether the discovery overlay is visible.
+     */
+    isVisible: boolean;
+    /**
+     * Ref to the target element to highlight.
+     */
+    targetRef: RefObject<MeasurableNode | null>;
+    /**
+     * Discovery title.
+     */
+    title: ReactNode;
+    /**
+     * Optional discovery description.
+     */
+    description?: ReactNode;
+    /**
+     * Optional action label displayed under the text.
+     */
+    actionText?: ReactNode;
+    /**
+     * Called when action text is pressed.
+     */
+    onActionPress?: () => void;
+    /**
+     * Called when overlay should close.
+     */
+    onDismiss?: () => void;
+    /**
+     * Whether tapping outside dismisses the overlay.
+     * @default true
+     */
+    dismissOnBackdropPress?: boolean;
+    /**
+     * Accent color for the discovery circle.
+     * @default 'primary'
+     */
+    themeColor?: ThemeColor;
+    /**
+     * Backdrop color.
+     */
+    overlayColor?: string;
+    /**
+     * Extra spacing around target highlight.
+     * @default 14
+     */
+    spotlightPadding?: number;
+    /**
+     * Scale multiplier for discovery circle diameter.
+     * @default 1.65
+     */
+    circleScale?: number;
+    /**
+     * Optional custom content rendered over the highlighted target.
+     */
+    highlightContent?: ReactNode;
+    /**
+     * Optional style overrides.
+     */
+    customAppearance?: FeatureDiscoveryCustomAppearance;
+};
+
+declare const FeatureDiscovery: React.FC<FeatureDiscoveryProps>;
+
+export { FeatureDiscovery, type FeatureDiscoveryCustomAppearance, type FeatureDiscoveryProps };