@cdx-ui/components 0.3.2 → 0.3.4

package/src/components/Insight/index.tsx

@@ -0,0 +1,531 @@
+import {
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react';
+import { Platform, Text, View, type TextProps, type ViewProps } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { useCSSVariable } from 'uniwind';
+import {
+  InsightRoot,
+  Slot,
+  dataAttributes,
+  mergeDataAttributes,
+  useInsightContext,
+  type IInsightDetailProps,
+  type IInsightProps,
+  type IInsightSummaryProps,
+} from '@cdx-ui/primitives';
+import { Close, Sparkle } from '@cdx-ui/icons';
+import { cn, createContext, ParentContext, useParentContext, useStyleContext } from '@cdx-ui/utils';
+import { Avatar } from '../Avatar';
+import { Chip } from '../Chip';
+import { IconButton } from '../IconButton';
+import { useCombinedAnimationDisabledState } from '../../animation';
+import { insetRadius } from './insetRadius';
+import {
+  FRAME_WIDTH,
+  insightCloseVariants,
+  insightContentVariants,
+  insightDescriptionVariants,
+  insightFooterVariants,
+  insightFrameVariants,
+  insightHeaderVariants,
+  insightIconVariants,
+  insightPressRegionVariants,
+  insightSummaryTextVariants,
+  insightSurfaceVariants,
+  insightTagIconVariants,
+  insightTagVariants,
+  insightTitleVariants,
+} from './styles';
+
+const SCOPE = 'INSIGHT';
+
+type InsightColor = 'info' | 'warning' | 'danger';
+
+interface InsightStyleContextValue {
+  layout: 'summary' | 'detail';
+  color: InsightColor;
+  hasClose: boolean;
+}
+
+const useInsightStyleContext = () => useStyleContext(SCOPE) as unknown as InsightStyleContextValue;
+
+type RegisteredInsightTag = InsightTagProps & { ref?: Ref<View> };
+
+interface InsightTagRegistry {
+  /** `owner` identifies the Tag instance, so one Tag unmounting never clears another's registration. */
+  registerTag: (owner: object, tag: RegisteredInsightTag | null) => void;
+}
+
+const [InsightTagRegistryProvider, useInsightTagRegistry] =
+  createContext<InsightTagRegistry>('InsightTagRegistry');
+
+let hasWarnedMissingTag = false;
+
+const PRESSED_SCALE = 0.98;
+const PRESS_SCALE_DURATION_MS = 120;
+
+// =============================================================================
+// ROOT
+// =============================================================================
+
+interface InsightStyleProps {
+  /**
+   * Tints the border, the summary medallion, and the detail tag. Visual only: any meaning it
+   * carries must also be in the text.
+   * @default 'info'
+   */
+  color?: 'info' | 'warning' | 'danger';
+  /**
+   * Swaps the `color` border for the AI gradient border.
+   * @default false
+   */
+  aiGenerated?: boolean;
+  /** Renders a dismiss button at the top-end corner. In `summary`, it sits beside the press region, not inside it. */
+  onClose?: () => void;
+  /**
+   * Accessible name for the dismiss button.
+   * @default 'Dismiss insight'
+   */
+  closeAccessibilityLabel?: string;
+}
+
+/**
+ * `className` and `style` style the outer frame (the border). `asChild` replaces the inner
+ * surface element. `onPress` exists only on `layout="summary"`.
+ *
+ * `ref` targets the element that takes focus: the press region of a summary with `onPress`
+ * (the surface, or the region beside the dismiss button when `onClose` is also set), so
+ * `ref.current?.focus()` moves focus to the card. A static Insight puts `ref` on its surface.
+ */
+export type InsightProps =
+  | (Omit<IInsightSummaryProps, 'accessory' | 'pressableClassName'> & InsightStyleProps)
+  | (Omit<IInsightDetailProps, 'accessory' | 'pressableClassName'> & InsightStyleProps);
+
+/**
+ * Press state lives in InsightRoot's context, but the scaled element is the frame around it, so
+ * this child of the root writes the frame's shared value.
+ */
+function InsightPressScale({ scale }: { scale: SharedValue<number> }) {
+  const { isPressed, isPressable } = useInsightContext();
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(undefined);
+
+  useEffect(() => {
+    if (!isPressable || isAllAnimationsDisabled) {
+      scale.set(1);
+      return;
+    }
+    scale.set(withTiming(isPressed ? PRESSED_SCALE : 1, { duration: PRESS_SCALE_DURATION_MS }));
+  }, [scale, isPressed, isPressable, isAllAnimationsDisabled]);
+
+  return null;
+}
+
+function SummaryBody({
+  hasClose,
+  scale,
+  children,
+}: {
+  hasClose: boolean;
+  scale: SharedValue<number>;
+  children?: ReactNode;
+}) {
+  const { color } = useInsightStyleContext();
+
+  return (
+    <>
+      <InsightPressScale scale={scale} />
+      <View
+        aria-hidden
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        {...dataAttributes({ slot: 'insight-icon' })}
+      >
+        <Avatar size="md" variant="subtle" color={color}>
+          <Avatar.Icon as={Sparkle} className={insightIconVariants({ color })} />
+        </Avatar>
+      </View>
+      <View className={insightSummaryTextVariants({ hasClose })}>{children}</View>
+    </>
+  );
+}
+
+const InsightRootStyled = forwardRef<View, InsightProps>((props, ref) => {
+  const {
+    color = 'info',
+    aiGenerated = false,
+    onClose,
+    closeAccessibilityLabel = 'Dismiss insight',
+    asChild = false,
+    className,
+    style,
+    children,
+    ...rootProps
+  } = props;
+  const layout = props.layout ?? 'summary';
+  const onPress = props.layout !== 'detail' ? props.onPress : undefined;
+  const isDisabled = props.layout !== 'detail' && !!props.isDisabled;
+  const hasClose = !!onClose;
+  const asChildElement = asChild && isValidElement(children);
+  const isPressable = layout === 'summary' && !!onPress;
+  // Mirrors InsightRoot: an accessory splits a pressable or `asChild` root into a container
+  // and a press region.
+  const isSplit = hasClose && (isPressable || asChildElement);
+
+  // The frame scales, not the press region, so the border and the close button move with it.
+  const scale = useSharedValue(1);
+  // Explicit deps for Vite/web without the Reanimated Babel plugin.
+  const pressScaleStyle = useAnimatedStyle(
+    () => ({ transform: [{ scale: scale.get() }] }),
+    [scale],
+  );
+
+  const [tag, setTag] = useState<RegisteredInsightTag | null>(null);
+  const tagOwnerRef = useRef<object | null>(null);
+  const registerTag = useCallback((owner: object, next: RegisteredInsightTag | null) => {
+    if (next) {
+      tagOwnerRef.current = owner;
+      setTag(next);
+    } else if (tagOwnerRef.current === owner) {
+      tagOwnerRef.current = null;
+      setTag(null);
+    }
+  }, []);
+  const registry = useMemo(() => ({ registerTag }), [registerTag]);
+
+  useEffect(() => {
+    if (__DEV__ && layout === 'detail' && tagOwnerRef.current === null && !hasWarnedMissingTag) {
+      hasWarnedMissingTag = true;
+      console.warn(
+        '[Insight] A `layout="detail"` Insight needs an `Insight.Tag` child. The design has no tagless detail layout.',
+      );
+    }
+  }, [layout]);
+
+  // A runtime override reaches native as a `px` string, which a `calc()` class turns into NaN.
+  // Web keeps the `calc()` class, which tracks the root font size and scoped overrides.
+  const radiusVariable = useCSSVariable('--border-radius-default');
+  const surfaceRadius =
+    Platform.OS === 'web' ? undefined : insetRadius(radiusVariable, FRAME_WIDTH);
+  const surfaceStyle = useMemo(
+    () => (surfaceRadius === undefined ? undefined : { borderRadius: surfaceRadius }),
+    [surfaceRadius],
+  );
+
+  const parent = useParentContext();
+  const ctx = useMemo(
+    () => ({ ...parent, [SCOPE]: { layout, color, hasClose } }),
+    [parent, layout, color, hasClose],
+  );
+
+  let content: ReactNode = children;
+  if (layout === 'summary') {
+    content = asChildElement ? (
+      cloneElement(
+        children as ReactElement<{ children?: ReactNode }>,
+        undefined,
+        <SummaryBody hasClose={hasClose} scale={scale}>
+          {(children as ReactElement<{ children?: ReactNode }>).props.children}
+        </SummaryBody>,
+      )
+    ) : (
+      <SummaryBody hasClose={hasClose} scale={scale}>
+        {children}
+      </SummaryBody>
+    );
+  }
+
+  const closeButton = onClose ? (
+    <IconButton
+      as={Close}
+      variant="ghost"
+      size="small"
+      color="neutral"
+      onPress={onClose}
+      accessibilityLabel={closeAccessibilityLabel}
+      className={insightCloseVariants()}
+      {...dataAttributes({ slot: 'insight-close' })}
+    />
+  ) : undefined;
+
+  return (
+    <ParentContext.Provider value={ctx}>
+      <InsightTagRegistryProvider value={registry}>
+        <Animated.View
+          className={cn(insightFrameVariants({ layout, color, aiGenerated }), className)}
+          style={isPressable ? [style, pressScaleStyle] : style}
+          {...dataAttributes({
+            slot: 'insight-frame',
+            ...(isPressable && { disabled: isDisabled }),
+          })}
+        >
+          {layout === 'detail' && tag ? <InsightTagChip {...tag} /> : null}
+          <InsightRoot
+            {...(rootProps as IInsightProps)}
+            ref={ref}
+            asChild={asChild}
+            style={surfaceStyle}
+            accessory={closeButton}
+            className={insightSurfaceVariants({ layout, split: isSplit })}
+            pressableClassName={
+              isSplit && layout === 'summary' ? insightPressRegionVariants() : undefined
+            }
+            {...mergeDataAttributes(rootProps, dataAttributes({ slot: 'insight' }))}
+          >
+            {content}
+          </InsightRoot>
+        </Animated.View>
+      </InsightTagRegistryProvider>
+    </ParentContext.Provider>
+  );
+});
+
+InsightRootStyled.displayName = 'Insight';
+
+// =============================================================================
+// TAG
+// =============================================================================
+
+export interface InsightTagProps extends ViewProps {
+  /** Merges the label props onto a single text child instead of rendering `Text`. */
+  asChild?: boolean;
+  /** Classes for the positioned tag wrapper. */
+  className?: string;
+  /** The insight's category, read before the title. */
+  children?: ReactNode;
+}
+
+function InsightTagChip({
+  asChild,
+  className,
+  style,
+  children,
+  ref,
+  ...props
+}: RegisteredInsightTag) {
+  const { color } = useInsightStyleContext();
+
+  return (
+    <View
+      ref={ref}
+      className={cn(insightTagVariants(), className)}
+      style={style}
+      {...props}
+      {...mergeDataAttributes(props, dataAttributes({ slot: 'insight-tag' }))}
+    >
+      <Chip variant="subtle" size="small" color={color}>
+        <Chip.Icon as={Sparkle} position="leading" className={insightTagIconVariants({ color })} />
+        <Chip.Label asChild={asChild}>{children}</Chip.Label>
+      </Chip>
+    </View>
+  );
+}
+
+/**
+ * The detail layout's category tag. Insight renders it as a Sparkle chip straddling the top
+ * border, ahead of the header in reading order, wherever it appears among the children.
+ */
+const InsightTag = forwardRef<View, InsightTagProps>((props, ref) => {
+  const { registerTag } = useInsightTagRegistry();
+  const [owner] = useState(() => ({}));
+
+  useLayoutEffect(() => {
+    registerTag(owner, { ...props, ref });
+  }, [registerTag, owner, props, ref]);
+
+  useLayoutEffect(() => () => registerTag(owner, null), [registerTag, owner]);
+
+  return null;
+});
+
+InsightTag.displayName = 'Insight.Tag';
+
+// =============================================================================
+// HEADER
+// =============================================================================
+
+export interface InsightHeaderProps extends ViewProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const InsightHeader = forwardRef<View, InsightHeaderProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(insightHeaderVariants(), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'insight-header' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+InsightHeader.displayName = 'Insight.Header';
+
+// =============================================================================
+// TITLE
+// =============================================================================
+
+export interface InsightTitleProps extends TextProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const InsightTitle = forwardRef<Text, InsightTitleProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const { hasClose } = useInsightStyleContext();
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        role="heading"
+        className={cn(insightTitleVariants({ hasClose }), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'insight-title' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+InsightTitle.displayName = 'Insight.Title';
+
+// =============================================================================
+// DESCRIPTION
+// =============================================================================
+
+export interface InsightDescriptionProps extends TextProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const InsightDescription = forwardRef<Text, InsightDescriptionProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(insightDescriptionVariants(), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'insight-description' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+InsightDescription.displayName = 'Insight.Description';
+
+// =============================================================================
+// CONTENT
+// =============================================================================
+
+export interface InsightContentProps extends ViewProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const InsightContent = forwardRef<View, InsightContentProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(insightContentVariants(), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'insight-content' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+InsightContent.displayName = 'Insight.Content';
+
+// =============================================================================
+// FOOTER
+// =============================================================================
+
+export interface InsightFooterProps extends ViewProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const InsightFooter = forwardRef<View, InsightFooterProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(insightFooterVariants(), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'insight-footer' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+InsightFooter.displayName = 'Insight.Footer';
+
+// =============================================================================
+// COMPOUND COMPONENT
+// =============================================================================
+
+type InsightCompoundComponent = typeof InsightRootStyled & {
+  Tag: typeof InsightTag;
+  Header: typeof InsightHeader;
+  Title: typeof InsightTitle;
+  Description: typeof InsightDescription;
+  Content: typeof InsightContent;
+  Footer: typeof InsightFooter;
+};
+
+export const Insight = Object.assign(InsightRootStyled, {
+  Tag: InsightTag,
+  Header: InsightHeader,
+  Title: InsightTitle,
+  Description: InsightDescription,
+  Content: InsightContent,
+  Footer: InsightFooter,
+}) as InsightCompoundComponent;

package/src/components/Insight/insetRadius.ts

@@ -0,0 +1,30 @@
+const ROOT_FONT_SIZE_PX = 16;
+
+const LENGTH_PATTERN = /^(-?\d*\.?\d+)(px|rem)?$/;
+
+/**
+ * Converts a resolved CSS variable (a number, or a `px`/`rem` string) to pixels. Native resolves
+ * built-in tokens to numbers, while runtime theme overrides and the web resolve to strings.
+ */
+export function cssLengthToPx(value: string | number | undefined): number | undefined {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const match = LENGTH_PATTERN.exec(value.trim());
+  if (!match) {
+    return undefined;
+  }
+
+  const amount = Number(match[1]);
+  return match[2] === 'rem' ? amount * ROOT_FONT_SIZE_PX : amount;
+}
+
+/** The radius of a surface inset `inset` px inside a frame with radius `outer`, or `undefined` when `outer` is not a length. */
+export function insetRadius(outer: string | number | undefined, inset: number): number | undefined {
+  const px = cssLengthToPx(outer);
+  return px === undefined ? undefined : Math.max(0, px - inset);
+}