{"version":3,"file":"ContextAwareBox.mjs","sources":["../../../../src/lib/layouts/context-aware/ContextAwareBox.tsx"],"sourcesContent":["/**\n * @fileoverview Context-Aware Box Component\n *\n * A generic container component that is aware of its DOM context\n * and can optionally provide that context to its children.\n *\n * Features:\n * - Knows its position in the layout hierarchy\n * - Can respond to context changes\n * - Provides layout hints to children\n * - Supports polymorphic rendering (as prop)\n *\n * @module layouts/context-aware/ContextAwareBox\n * @author Agent 4 - PhD Context Systems Expert\n * @version 1.0.0\n */\n\nimport React, {\n  useRef,\n  useEffect,\n  type ReactNode,\n  useCallback,\n  forwardRef,\n  type ElementType,\n  type ComponentPropsWithoutRef,\n  type JSX,\n} from 'react';\n\nimport type { DOMContext, LayoutType, ContextAwareBoxProps } from './types';\nimport { useDOMContextValue } from './DOMContextProvider';\nimport { getDOMContextTracker } from './dom-context';\n// import { getZIndexManager } from './z-index-manager';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Props for polymorphic ContextAwareBox.\n */\nexport type PolymorphicContextAwareBoxProps<E extends ElementType> = ContextAwareBoxProps & {\n  as?: E;\n} & Omit<ComponentPropsWithoutRef<E>, keyof ContextAwareBoxProps>;\n\n/**\n * Extended context information specific to the box.\n */\nexport interface BoxContext extends DOMContext {\n  /** The box's own layout type */\n  ownLayoutType: LayoutType;\n  /** Whether this box is the nearest layout ancestor for children */\n  isLayoutRoot: boolean;\n  /** Depth in the context tree */\n  contextDepth: number;\n}\n\n/**\n * Callback for context ready event.\n */\nexport type OnContextReadyCallback = (context: DOMContext, element: HTMLElement) => void;\n\n// ============================================================================\n// ContextAwareBox Component\n// ============================================================================\n\n/**\n * A context-aware container component.\n *\n * @remarks\n * This component is aware of its DOM context and can provide\n * useful layout information to its children. It's useful for\n * building responsive components that adapt to their container.\n *\n * @example\n * ```tsx\n * // Basic usage\n * <ContextAwareBox>\n *   <MyContent />\n * </ContextAwareBox>\n *\n * // With context callback\n * <ContextAwareBox onContextReady={(ctx) => console.log(ctx)}>\n *   <MyContent />\n * </ContextAwareBox>\n *\n * // Polymorphic rendering\n * <ContextAwareBox as=\"section\" className=\"my-section\">\n *   <MyContent />\n * </ContextAwareBox>\n *\n * // With layout hint for children\n * <ContextAwareBox layoutHint=\"flex\">\n *   <FlexChild />\n * </ContextAwareBox>\n * ```\n */\nfunction ContextAwareBoxInner<E extends ElementType = 'div'>(\n  {\n    as,\n    children,\n    className,\n    style,\n    provideContext: _provideContext = false,\n    onContextReady,\n    layoutHint,\n    'data-testid': testId,\n    ...restProps\n  }: PolymorphicContextAwareBoxProps<E>,\n  forwardedRef: React.ForwardedRef<HTMLElement>\n): JSX.Element {\n  // Determine the component to render\n  const Component = as ?? 'div';\n\n  // Refs\n  const internalRef = useRef<HTMLElement>(null);\n  const contextReadyCalledRef = useRef(false);\n\n  // Get DOM context\n  const domContext = useDOMContextValue();\n  // const _refreshContext = useDOMContextRefresh();\n\n  // Resolve ref\n  const resolvedRef = (forwardedRef ?? internalRef) as React.RefObject<HTMLElement>;\n\n  /**\n   * Computes box-specific context information.\n   * Currently unused but kept for future use.\n   */\n  const _computeBoxContext = useCallback((): BoxContext | null => {\n    if (\n      resolvedRef.current === null ||\n      resolvedRef.current === undefined ||\n      !domContext.isInitialized\n    ) {\n      return null;\n    }\n\n    const tracker = getDOMContextTracker();\n    const element = resolvedRef.current;\n\n    // Get this element's layout type\n    const ownLayoutType = tracker.getLayoutType(element);\n\n    // Determine if this is a layout root\n    const isLayoutRoot =\n      ownLayoutType === 'flex' ||\n      ownLayoutType === 'grid' ||\n      ownLayoutType === 'inline-flex' ||\n      ownLayoutType === 'inline-grid';\n\n    // Calculate context depth\n    const contextDepth = domContext.ancestors.length;\n\n    return {\n      ...domContext,\n      ownLayoutType,\n      isLayoutRoot,\n      contextDepth,\n    };\n  }, [domContext, resolvedRef]);\n\n  // Suppress unused variable warning\n  void _computeBoxContext;\n\n  // Call onContextReady when context is initialized\n  useEffect(() => {\n    if (\n      domContext.isInitialized &&\n      resolvedRef.current !== null &&\n      resolvedRef.current !== undefined &&\n      onContextReady !== undefined &&\n      !contextReadyCalledRef.current\n    ) {\n      contextReadyCalledRef.current = true;\n      onContextReady(domContext);\n    }\n  }, [domContext.isInitialized, onContextReady, resolvedRef, domContext]);\n\n  // Re-trigger context ready if element changes\n  useEffect(() => {\n    if (resolvedRef.current !== null && resolvedRef.current !== undefined) {\n      contextReadyCalledRef.current = false;\n    }\n  }, [resolvedRef]);\n\n  // Compute style with layout hint\n  const computedStyle = React.useMemo(() => {\n    if (!layoutHint) {\n      return style;\n    }\n\n    const layoutStyles: React.CSSProperties = {};\n\n    switch (layoutHint) {\n      case 'flex':\n        layoutStyles.display = 'flex';\n        break;\n      case 'inline-flex':\n        layoutStyles.display = 'inline-flex';\n        break;\n      case 'grid':\n        layoutStyles.display = 'grid';\n        break;\n      case 'inline-grid':\n        layoutStyles.display = 'inline-grid';\n        break;\n      case 'block':\n        layoutStyles.display = 'block';\n        break;\n      case 'inline':\n        layoutStyles.display = 'inline';\n        break;\n      case 'inline-block':\n        layoutStyles.display = 'inline-block';\n        break;\n    }\n\n    return { ...layoutStyles, ...style };\n  }, [layoutHint, style]);\n\n  // Build data attributes\n  const dataAttributes: Record<string, string> = {\n    'data-context-aware': 'true',\n  };\n\n  if (layoutHint) {\n    dataAttributes['data-layout-hint'] = layoutHint;\n  }\n\n  if (domContext.isInitialized) {\n    dataAttributes['data-context-initialized'] = 'true';\n    dataAttributes['data-context-id'] = domContext.contextId;\n  }\n\n  const ElementComponent = Component as unknown as React.ComponentType<{\n    ref: React.Ref<HTMLElement>;\n    className?: string;\n    style?: React.CSSProperties;\n    'data-testid'?: string;\n    children?: ReactNode;\n    [key: string]: unknown;\n  }>;\n\n  return (\n    <ElementComponent\n      ref={resolvedRef as React.Ref<HTMLElement>}\n      className={className}\n      style={computedStyle}\n      data-testid={testId}\n      {...dataAttributes}\n      {...(restProps as Record<string, unknown>)}\n    >\n      {children}\n    </ElementComponent>\n  );\n}\n\n/**\n * Forwarded ref version of ContextAwareBox.\n */\nexport const ContextAwareBox = forwardRef(ContextAwareBoxInner) as <E extends ElementType = 'div'>(\n  props: PolymorphicContextAwareBoxProps<E> & {\n    ref?: React.ForwardedRef<HTMLElement>;\n  }\n) => JSX.Element;\n\n// ============================================================================\n// Specialized Box Variants\n// ============================================================================\n\n/**\n * Props for FlexBox component.\n */\nexport interface FlexBoxProps extends Omit<ContextAwareBoxProps, 'layoutHint' | 'as'> {\n  /** Flex direction */\n  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';\n  /** Justify content */\n  justify?: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly';\n  /** Align items */\n  align?: 'start' | 'end' | 'center' | 'stretch' | 'baseline';\n  /** Flex wrap */\n  wrap?: boolean | 'reverse';\n  /** Gap between items */\n  gap?: number | string;\n}\n\n/**\n * Context-aware flex container.\n *\n * @example\n * ```tsx\n * <FlexBox direction=\"column\" justify=\"center\" gap={16}>\n *   <Item />\n *   <Item />\n * </FlexBox>\n * ```\n */\nexport function FlexBox({\n  direction = 'row',\n  justify,\n  align,\n  wrap,\n  gap,\n  style,\n  ...props\n}: FlexBoxProps): JSX.Element {\n  // Compute flex wrap value\n  let flexWrapValue: 'wrap' | 'wrap-reverse' | undefined;\n  if (wrap === true) {\n    flexWrapValue = 'wrap';\n  } else if (wrap === 'reverse') {\n    flexWrapValue = 'wrap-reverse';\n  } else {\n    flexWrapValue = undefined;\n  }\n\n  const flexStyle: React.CSSProperties = {\n    display: 'flex',\n    flexDirection: direction,\n    justifyContent: justify !== undefined ? mapJustify(justify) : undefined,\n    alignItems: align !== undefined ? mapAlign(align) : undefined,\n    flexWrap: flexWrapValue,\n    gap: typeof gap === 'number' ? `${gap}px` : gap,\n    ...style,\n  };\n\n  return <ContextAwareBox style={flexStyle} {...props} />;\n}\n\n/**\n * Props for GridBox component.\n */\nexport interface GridBoxProps extends Omit<ContextAwareBoxProps, 'layoutHint' | 'as'> {\n  /** Number of columns or template string */\n  columns?: number | string;\n  /** Number of rows or template string */\n  rows?: number | string;\n  /** Gap between items */\n  gap?: number | string;\n  /** Row gap */\n  rowGap?: number | string;\n  /** Column gap */\n  columnGap?: number | string;\n  /** Auto flow direction */\n  autoFlow?: 'row' | 'column' | 'dense' | 'row dense' | 'column dense';\n}\n\n/**\n * Context-aware grid container.\n *\n * @example\n * ```tsx\n * <GridBox columns={3} gap={16}>\n *   <Item />\n *   <Item />\n *   <Item />\n * </GridBox>\n * ```\n */\nexport function GridBox({\n  columns,\n  rows,\n  gap,\n  rowGap,\n  columnGap,\n  autoFlow,\n  style,\n  ...props\n}: GridBoxProps): JSX.Element {\n  const gridStyle: React.CSSProperties = {\n    display: 'grid',\n    gridTemplateColumns: typeof columns === 'number' ? `repeat(${columns}, 1fr)` : columns,\n    gridTemplateRows: typeof rows === 'number' ? `repeat(${rows}, 1fr)` : rows,\n    gap: typeof gap === 'number' ? `${gap}px` : gap,\n    rowGap: typeof rowGap === 'number' ? `${rowGap}px` : rowGap,\n    columnGap: typeof columnGap === 'number' ? `${columnGap}px` : columnGap,\n    gridAutoFlow: autoFlow,\n    ...style,\n  };\n\n  return <ContextAwareBox style={gridStyle} {...props} />;\n}\n\n// ============================================================================\n// Utility Functions\n// ============================================================================\n\n/**\n * Maps justify prop to CSS value.\n */\nfunction mapJustify(justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'): string {\n  const map: Record<typeof justify, string> = {\n    start: 'flex-start',\n    end: 'flex-end',\n    center: 'center',\n    between: 'space-between',\n    around: 'space-around',\n    evenly: 'space-evenly',\n  };\n  return map[justify];\n}\n\n/**\n * Maps align prop to CSS value.\n */\nfunction mapAlign(align: 'start' | 'end' | 'center' | 'stretch' | 'baseline'): string {\n  const map: Record<typeof align, string> = {\n    start: 'flex-start',\n    end: 'flex-end',\n    center: 'center',\n    stretch: 'stretch',\n    baseline: 'baseline',\n  };\n  return map[align];\n}\n"],"names":["ContextAwareBoxInner","as","children","className","style","_provideContext","onContextReady","layoutHint","testId","restProps","forwardedRef","Component","internalRef","useRef","contextReadyCalledRef","domContext","useDOMContextValue","resolvedRef","useCallback","tracker","getDOMContextTracker","element","ownLayoutType","isLayoutRoot","contextDepth","useEffect","computedStyle","React","layoutStyles","dataAttributes","jsx","ContextAwareBox","forwardRef","FlexBox","direction","justify","align","wrap","gap","props","flexWrapValue","flexStyle","mapJustify","mapAlign","GridBox","columns","rows","rowGap","columnGap","autoFlow","gridStyle"],"mappings":"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"}