@startupjs-ui/abstract-popover 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.1.3](https://github.com/startupjs/startupjs-ui/compare/v0.1.2...v0.1.3) (2025-12-29)
+
+**Note:** Version bump only for package @startupjs-ui/abstract-popover
+
+
+
+
+
+## [0.1.2](https://github.com/startupjs/startupjs-ui/compare/v0.1.1...v0.1.2) (2025-12-29)
+
+
+### Features
+
+* **abstract-popover:** refactor AbstractPopover component ([4a19018](https://github.com/startupjs/startupjs-ui/commit/4a190183b9e6903b6758d1d006fce7eca39bce0a))
+* add mdx and docs packages. Refactor docs to get rid of any @startupjs/ui usage and use startupjs-ui instead ([703c926](https://github.com/startupjs/startupjs-ui/commit/703c92636efb0421ffd11783f692fc892b74018f))

package/README.mdx

@@ -0,0 +1,156 @@
+import { useRef, useState } from 'react'
+import { Sandbox } from '@startupjs-ui/docs'
+import AbstractPopover, {
+  _PropsJsonSchema as AbstractPopoverPropsJsonSchema
+} from './index'
+import Button from '@startupjs-ui/button'
+import Div from '@startupjs-ui/div'
+import Span from '@startupjs-ui/span'
+
+# AbstractPopover
+
+Low-level primitive for anchoring content to an element (tooltip / popover use-cases).
+
+```jsx
+import { AbstractPopover } from 'startupjs-ui'
+```
+
+## Basic example
+
+```jsx example
+const anchorRef = useRef()
+const [visible, setVisible] = useState(false)
+
+return (
+  <Div style={{ padding: 20, backgroundColor: '#f6f7f9' }}>
+    <Div row gap style={{ alignItems: 'center' }}>
+      <Button onPress={() => setVisible(v => !v)}>
+        Toggle popover
+      </Button>
+      <Div
+        ref={anchorRef}
+        style={{
+          padding: 10,
+          backgroundColor: 'white',
+          borderRadius: 8,
+          borderWidth: 1,
+          borderColor: '#ddd'
+        }}
+      >
+        <Span>Anchor</Span>
+      </Div>
+    </Div>
+
+    <AbstractPopover
+      anchorRef={anchorRef}
+      visible={visible}
+      arrow
+      position='bottom'
+      attachment='start'
+      style={{
+        backgroundColor: 'white',
+        padding: 10,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: '#ddd'
+      }}
+    >
+      <Span>Popover content</Span>
+    </AbstractPopover>
+  </Div>
+)
+```
+
+## Matching anchor width
+
+```jsx example
+const anchorRef = useRef()
+const [visible, setVisible] = useState(false)
+
+return (
+  <Div style={{ padding: 20, backgroundColor: '#f6f7f9' }}>
+    <Div
+      ref={anchorRef}
+      style={{
+        width: 240,
+        padding: 10,
+        backgroundColor: 'white',
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: '#ddd'
+      }}
+    >
+      <Span>Anchor (240px)</Span>
+      <Button pushed onPress={() => setVisible(v => !v)}>
+        Toggle
+      </Button>
+    </Div>
+
+    <AbstractPopover
+      anchorRef={anchorRef}
+      visible={visible}
+      matchAnchorWidth
+      position='bottom'
+      attachment='start'
+      style={{
+        backgroundColor: 'white',
+        padding: 10,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: '#ddd'
+      }}
+    >
+      <Span>Width matches anchor</Span>
+    </AbstractPopover>
+  </Div>
+)
+```
+
+## Custom fallback placements
+
+```jsx example
+const anchorRef = useRef()
+const [visible, setVisible] = useState(false)
+
+return (
+  <Div style={{ padding: 20, backgroundColor: '#f6f7f9' }}>
+    <Div ref={anchorRef} style={{ padding: 10, backgroundColor: 'white', borderRadius: 8 }}>
+      <Span>Anchor</Span>
+      <Button pushed onPress={() => setVisible(v => !v)}>
+        Toggle
+      </Button>
+    </Div>
+
+    <AbstractPopover
+      anchorRef={anchorRef}
+      visible={visible}
+      position='top'
+      attachment='center'
+      placements={['top-center', 'bottom-center']}
+      arrow
+      style={{
+        backgroundColor: 'white',
+        padding: 10,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: '#ddd'
+      }}
+    >
+      <Span>Tries top-center, then bottom-center</Span>
+    </AbstractPopover>
+  </Div>
+)
+```
+
+## Sandbox
+
+<Sandbox
+  Component={AbstractPopover}
+  propsJsonSchema={AbstractPopoverPropsJsonSchema}
+  props={{
+    anchorRef: { current: { measure: (cb) => cb(0, 0, 120, 32, 40, 120) } },
+    style: { backgroundColor: 'white', padding: 10, borderRadius: 8, borderWidth: 1, borderColor: '#ddd' },
+    arrow: true,
+    children: <Span>Sandbox content</Span>
+  }}
+/>

package/constants.ts

@@ -0,0 +1,35 @@
+export const POPOVER_MARGIN = 8 as const
+export const ARROW_SIZE = 8 as const
+
+export type AbstractPopoverPosition = 'top' | 'bottom' | 'left' | 'right'
+export type AbstractPopoverAttachment = 'start' | 'center' | 'end'
+export type AbstractPopoverPlacement = `${AbstractPopoverPosition}-${AbstractPopoverAttachment}`
+
+export const STEPS = {
+  CLOSE: 'close',
+  MEASURE: 'measure',
+  RENDER: 'render',
+  OPEN: 'open'
+} as const
+
+export const PLACEMENTS_ORDER = [
+  'top-start',
+  'top-center',
+  'top-end',
+  'right-start',
+  'right-center',
+  'right-end',
+  'bottom-end',
+  'bottom-center',
+  'bottom-start',
+  'left-end',
+  'left-center',
+  'left-start'
+] as const satisfies readonly AbstractPopoverPlacement[]
+
+export const POSITIONS_REVERSE = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left'
+} as const

package/getGeometry.ts

@@ -0,0 +1,459 @@
+import { Dimensions } from 'react-native'
+import {
+  ARROW_SIZE,
+  PLACEMENTS_ORDER,
+  POPOVER_MARGIN,
+  POSITIONS_REVERSE,
+  type AbstractPopoverAttachment as Attachment,
+  type AbstractPopoverPlacement as Placement,
+  type AbstractPopoverPosition as Position
+} from './constants'
+
+interface Measures {
+  width: number
+  height: number
+}
+
+interface LayoutMeasures {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+interface AnchorMeasures extends LayoutMeasures {
+  pageX: number
+  pageY: number
+}
+
+export interface PopoverGeometry {
+  placement: Placement
+  position: Position
+  attachment: Attachment
+  top: number
+  left: number
+  arrowTop: number | string
+  arrowLeft: number | string
+  width: number
+}
+
+export default function getGeometry (params: {
+  placement: Placement
+  placements: readonly Placement[]
+  arrow?: boolean
+  matchAnchorWidth?: boolean
+  dimensions: Measures
+  tetherMeasures: LayoutMeasures & Measures
+  anchorMeasures: AnchorMeasures
+}): PopoverGeometry {
+  const {
+    placement,
+    placements,
+    matchAnchorWidth,
+    tetherMeasures,
+    anchorMeasures
+  } = params
+  const topPositions = getTopPositions(params)
+  const leftPositions = getLeftPositions(params)
+  const arrowTopPositions = getTopPositionsArrow(params)
+  const arrowLeftPositions = getLeftPositionsArrow(params)
+  const preparedPlacements = preparePlacements({ placement, placements })
+  const currentPlacement = findAvailablePlacement({
+    tetherMeasures,
+    placement,
+    placements: preparedPlacements,
+    leftPositions,
+    topPositions,
+    initPlacement: placement
+  })
+
+  const [currentPosition, currentAttachment] = currentPlacement.split('-') as [Position, Attachment]
+
+  const geometry = {
+    placement: currentPlacement,
+    position: currentPosition,
+    attachment: currentAttachment,
+    top: topPositions[currentPlacement],
+    left: leftPositions[currentPlacement],
+    arrowTop: arrowTopPositions[currentPlacement],
+    arrowLeft: arrowLeftPositions[currentPlacement],
+    width: matchAnchorWidth ? anchorMeasures.width : tetherMeasures.width
+  }
+
+  return geometry
+}
+
+function getLeftPositions ({
+  tetherMeasures,
+  anchorMeasures,
+  arrow,
+  dimensions
+}: {
+  tetherMeasures: Measures
+  anchorMeasures: AnchorMeasures
+  arrow?: boolean
+  dimensions: Measures
+}): Record<Placement, number> {
+  const leftPositions: Record<string, number> = {}
+
+  const halfContent = tetherMeasures.width / 2
+  const halfCaption = anchorMeasures.width / 2
+
+  const overRight = dimensions.width - tetherMeasures.width
+
+  const positionMinorLeft = anchorMeasures.pageX
+  if (positionMinorLeft + tetherMeasures.width > dimensions.width) {
+    leftPositions['bottom-start'] = overRight
+    leftPositions['top-start'] = overRight
+  } else {
+    leftPositions['bottom-start'] = positionMinorLeft
+    leftPositions['top-start'] = positionMinorLeft
+  }
+
+  const positionMinorCenter = anchorMeasures.pageX - halfContent + halfCaption
+  if (positionMinorCenter < 0) {
+    leftPositions['top-center'] = 0
+    leftPositions['bottom-center'] = 0
+  } else if (positionMinorCenter + tetherMeasures.width > dimensions.width) {
+    leftPositions['top-center'] = overRight
+    leftPositions['bottom-center'] = overRight
+  } else {
+    leftPositions['top-center'] = positionMinorCenter
+    leftPositions['bottom-center'] = positionMinorCenter
+  }
+
+  const positionMinorRight = anchorMeasures.pageX - tetherMeasures.width + anchorMeasures.width
+  if (positionMinorRight < 0) {
+    leftPositions['bottom-end'] = 0
+    leftPositions['top-end'] = 0
+  } else {
+    leftPositions['bottom-end'] = positionMinorRight
+    leftPositions['top-end'] = positionMinorRight
+  }
+
+  const positionRootLeft = anchorMeasures.pageX - tetherMeasures.width - (arrow ? ARROW_SIZE + POPOVER_MARGIN : POPOVER_MARGIN)
+  leftPositions['left-start'] = positionRootLeft
+  leftPositions['left-center'] = positionRootLeft
+  leftPositions['left-end'] = positionRootLeft
+
+  const positionRootRight = anchorMeasures.pageX + anchorMeasures.width + (arrow ? ARROW_SIZE + POPOVER_MARGIN : POPOVER_MARGIN)
+  leftPositions['right-start'] = positionRootRight
+  leftPositions['right-center'] = positionRootRight
+  leftPositions['right-end'] = positionRootRight
+
+  return leftPositions
+}
+
+function getTopPositions ({
+  anchorMeasures,
+  tetherMeasures,
+  arrow,
+  dimensions
+}: {
+  tetherMeasures: Measures
+  anchorMeasures: AnchorMeasures
+  arrow?: boolean
+  dimensions: Measures
+}): Record<Placement, number> {
+  const topPositions: Record<string, number> = {}
+
+  const halfCaption = anchorMeasures.height / 2
+  const halfContent = tetherMeasures.height / 2
+
+  const positionRootBottom = anchorMeasures.pageY + anchorMeasures.height + (arrow ? ARROW_SIZE + POPOVER_MARGIN : POPOVER_MARGIN)
+  topPositions['bottom-start'] = positionRootBottom
+  topPositions['bottom-center'] = positionRootBottom
+  topPositions['bottom-end'] = positionRootBottom
+
+  const positionRootTop = anchorMeasures.pageY - tetherMeasures.height - (arrow ? ARROW_SIZE + POPOVER_MARGIN : POPOVER_MARGIN)
+  topPositions['top-start'] = positionRootTop
+  topPositions['top-center'] = positionRootTop
+  topPositions['top-end'] = positionRootTop
+
+  const positionMinorCenter = anchorMeasures.pageY + halfCaption - halfContent
+  if (positionMinorCenter < 0) {
+    topPositions['left-center'] = 0
+    topPositions['right-center'] = 0
+  } else if (anchorMeasures.pageY + halfContent > dimensions.height) {
+    const positionMinorCenterOverBottom = dimensions.height - tetherMeasures.height
+    topPositions['left-center'] = positionMinorCenterOverBottom
+    topPositions['right-center'] = positionMinorCenterOverBottom
+  } else {
+    topPositions['left-center'] = positionMinorCenter
+    topPositions['right-center'] = positionMinorCenter
+  }
+
+  if (anchorMeasures.pageY + tetherMeasures.height > dimensions.height) {
+    const positionMinorStartOver = dimensions.height - tetherMeasures.height
+    topPositions['left-start'] = positionMinorStartOver
+    topPositions['right-start'] = positionMinorStartOver
+  } else {
+    topPositions['left-start'] = anchorMeasures.pageY
+    topPositions['right-start'] = anchorMeasures.pageY
+  }
+
+  if (anchorMeasures.pageY + anchorMeasures.height - tetherMeasures.height < 0) {
+    topPositions['left-end'] = 0
+    topPositions['right-end'] = 0
+  } else {
+    const positionMinorEnd = anchorMeasures.pageY + anchorMeasures.height - tetherMeasures.height
+    topPositions['left-end'] = positionMinorEnd
+    topPositions['right-end'] = positionMinorEnd
+  }
+
+  return topPositions
+}
+
+function getLeftPositionsArrow ({
+  tetherMeasures,
+  anchorMeasures,
+  dimensions
+}: {
+  tetherMeasures: Measures
+  anchorMeasures: AnchorMeasures
+  dimensions: Measures
+}): Record<Placement, number | string> {
+  const arrowLeftPositions: Record<string, number | string> = {}
+
+  const halfContent = tetherMeasures.width / 2
+  const halfCaption = anchorMeasures.width / 2
+
+  const overLeft = anchorMeasures.pageX + halfCaption - ARROW_SIZE
+  const overRight = tetherMeasures.width - (dimensions.width - anchorMeasures.pageX) + halfCaption - ARROW_SIZE
+  const minRight = tetherMeasures.width - (ARROW_SIZE * 3)
+
+  if (anchorMeasures.pageX + tetherMeasures.width > dimensions.width) {
+    if (anchorMeasures.pageX + anchorMeasures.width > dimensions.width) {
+      arrowLeftPositions['top-start'] = minRight
+      arrowLeftPositions['bottom-start'] = minRight
+    } else {
+      arrowLeftPositions['top-start'] = overRight
+      arrowLeftPositions['bottom-start'] = overRight
+    }
+  } else {
+    arrowLeftPositions['top-start'] = ARROW_SIZE
+    arrowLeftPositions['bottom-start'] = ARROW_SIZE
+  }
+
+  if (anchorMeasures.pageX - tetherMeasures.width + anchorMeasures.width < 0) {
+    if (anchorMeasures.pageX < 0) {
+      arrowLeftPositions['top-end'] = ARROW_SIZE
+      arrowLeftPositions['bottom-end'] = ARROW_SIZE
+    } else {
+      arrowLeftPositions['top-end'] = overLeft
+      arrowLeftPositions['bottom-end'] = overLeft
+    }
+  } else {
+    const positionEnd = tetherMeasures.width - (ARROW_SIZE * 3)
+    arrowLeftPositions['top-end'] = positionEnd
+    arrowLeftPositions['bottom-end'] = positionEnd
+  }
+
+  if (anchorMeasures.pageX - halfContent + halfCaption < 0) {
+    if (anchorMeasures.pageX < 0) {
+      arrowLeftPositions['top-center'] = ARROW_SIZE
+      arrowLeftPositions['bottom-center'] = ARROW_SIZE
+    } else {
+      arrowLeftPositions['top-center'] = overLeft
+      arrowLeftPositions['bottom-center'] = overLeft
+    }
+  } else if (anchorMeasures.pageX + halfContent > dimensions.width) {
+    if (anchorMeasures.pageX + anchorMeasures.width > dimensions.width) {
+      arrowLeftPositions['top-center'] = minRight
+      arrowLeftPositions['bottom-center'] = minRight
+    } else {
+      arrowLeftPositions['top-center'] = overRight
+      arrowLeftPositions['bottom-center'] = overRight
+    }
+  } else {
+    const positionCenter = halfContent - ARROW_SIZE
+    arrowLeftPositions['top-center'] = positionCenter
+    arrowLeftPositions['bottom-center'] = positionCenter
+  }
+
+  arrowLeftPositions['left-center'] = '100%'
+  arrowLeftPositions['left-start'] = '100%'
+  arrowLeftPositions['left-end'] = '100%'
+
+  const dblArrow = ARROW_SIZE * 2
+  arrowLeftPositions['right-start'] = -dblArrow
+  arrowLeftPositions['right-center'] = -dblArrow
+  arrowLeftPositions['right-end'] = -dblArrow
+
+  return arrowLeftPositions
+}
+
+function getTopPositionsArrow ({
+  tetherMeasures,
+  anchorMeasures,
+  dimensions
+}: {
+  tetherMeasures: Measures
+  anchorMeasures: AnchorMeasures
+  dimensions: Measures
+}): Record<Placement, number> {
+  const arrowTopPositions: Record<string, number> = {}
+
+  const halfCaption = anchorMeasures.height / 2
+  const halfContent = tetherMeasures.height / 2
+
+  const overTop = anchorMeasures.pageX + halfCaption - ARROW_SIZE
+  const overBottom = tetherMeasures.height - (dimensions.height - anchorMeasures.pageX) + halfCaption - ARROW_SIZE
+  const minBottom = tetherMeasures.height - (ARROW_SIZE * 3)
+
+  if (anchorMeasures.pageX + halfCaption - halfContent < 0) {
+    if (anchorMeasures.pageX < 0) {
+      arrowTopPositions['left-center'] = ARROW_SIZE
+      arrowTopPositions['right-center'] = ARROW_SIZE
+    } else {
+      arrowTopPositions['left-center'] = overTop
+      arrowTopPositions['right-center'] = overTop
+    }
+  } else if (anchorMeasures.pageX + halfContent > dimensions.height) {
+    if (anchorMeasures.pageX + anchorMeasures.height > dimensions.height) {
+      arrowTopPositions['left-center'] = minBottom
+      arrowTopPositions['right-center'] = minBottom
+    } else {
+      arrowTopPositions['left-center'] = overBottom
+      arrowTopPositions['right-center'] = overBottom
+    }
+  } else {
+    const positionCenter = halfContent - ARROW_SIZE
+    arrowTopPositions['left-center'] = positionCenter
+    arrowTopPositions['right-center'] = positionCenter
+  }
+
+  if (anchorMeasures.pageX + tetherMeasures.height > dimensions.height) {
+    if (anchorMeasures.pageX + anchorMeasures.height > dimensions.height) {
+      arrowTopPositions['left-start'] = minBottom
+      arrowTopPositions['right-start'] = minBottom
+    } else {
+      arrowTopPositions['left-start'] = overBottom
+      arrowTopPositions['right-start'] = overBottom
+    }
+  } else {
+    const positionStart = ARROW_SIZE
+    arrowTopPositions['left-start'] = positionStart
+    arrowTopPositions['right-start'] = positionStart
+  }
+
+  if (anchorMeasures.pageX + anchorMeasures.height - tetherMeasures.height < 0) {
+    if (anchorMeasures.pageX < 0) {
+      arrowTopPositions['left-end'] = ARROW_SIZE
+      arrowTopPositions['right-end'] = ARROW_SIZE
+    } else {
+      arrowTopPositions['left-end'] = overTop
+      arrowTopPositions['right-end'] = overTop
+    }
+  } else {
+    const positionEnd = tetherMeasures.height - (ARROW_SIZE * 3)
+    arrowTopPositions['left-end'] = positionEnd
+    arrowTopPositions['right-end'] = positionEnd
+  }
+
+  arrowTopPositions['top-start'] = tetherMeasures.height
+  arrowTopPositions['top-center'] = tetherMeasures.height
+  arrowTopPositions['top-end'] = tetherMeasures.height
+
+  const dblArrow = ARROW_SIZE * 2
+  arrowTopPositions['bottom-start'] = -dblArrow
+  arrowTopPositions['bottom-center'] = -dblArrow
+  arrowTopPositions['bottom-end'] = -dblArrow
+
+  return arrowTopPositions
+}
+
+// TODO: This is unlogical behaviour.
+// We can always find a better position if the specified position does not fit
+function preparePlacements ({
+  placement,
+  placements
+}: {
+  placement: Placement
+  placements: readonly Placement[]
+}): Placement[] {
+  if (placements.length !== PLACEMENTS_ORDER.length) {
+    return PLACEMENTS_ORDER.filter(item => {
+      return placements.includes(item as Placement)
+    })
+  }
+
+  let _preparePlacements: Placement[] = [...PLACEMENTS_ORDER]
+
+  const activeIndexPlacement = _preparePlacements.findIndex(item => {
+    return item === placement
+  })
+
+  const activePlacement = _preparePlacements[activeIndexPlacement] ?? placement
+  const [position, attachment] = activePlacement.split('-') as [Position, Attachment]
+  const reversePlacement = `${POSITIONS_REVERSE[position]}-${attachment}` as Placement
+  const reverseIndexPlacement = _preparePlacements.findIndex(item => {
+    return item === reversePlacement
+  })
+  _preparePlacements = _preparePlacements.filter(item => {
+    return item !== reversePlacement
+  })
+
+  _preparePlacements = [
+    ..._preparePlacements.slice(0, activeIndexPlacement),
+    (PLACEMENTS_ORDER[reverseIndexPlacement] ?? reversePlacement) as Placement,
+    ..._preparePlacements.slice(activeIndexPlacement)
+  ]
+
+  return _preparePlacements
+}
+
+// TODO: This is unlogical behaviour.
+// We can always find a better position if the specified position does not fit
+function findAvailablePlacement (options: {
+  counter?: number
+  tetherMeasures: Measures
+  placement: Placement
+  placements: Placement[]
+  leftPositions: Record<Placement, number>
+  topPositions: Record<Placement, number>
+  initPlacement: Placement
+}): Placement {
+  const {
+    counter = 1,
+    tetherMeasures,
+    placement,
+    placements,
+    leftPositions,
+    topPositions,
+    initPlacement
+  } = options
+
+  if (counter > placements.length) {
+    return initPlacement
+  }
+
+  const activeIndexPlacement = placements.findIndex(item => {
+    return item === placement
+  })
+
+  let nextIndex = activeIndexPlacement + 1
+  if (nextIndex > placements.length - 1) nextIndex = 0
+
+  const _leftPosition = leftPositions[placement]
+  if (_leftPosition < 0 ||
+      _leftPosition + tetherMeasures.width > Dimensions.get('window').width) {
+    return findAvailablePlacement({
+      ...options,
+      counter: counter + 1,
+      placement: placements[nextIndex]
+    })
+  }
+
+  const _topPosition = topPositions[placement]
+  if (_topPosition < 0 ||
+    _topPosition + tetherMeasures.height > Dimensions.get('window').height) {
+    return findAvailablePlacement({
+      ...options,
+      counter: counter + 1,
+      placement: placements[nextIndex]
+    })
+  }
+
+  return placements[activeIndexPlacement] ?? initPlacement
+}

package/index.cssx.styl

@@ -0,0 +1,18 @@
+.root
+  position absolute
+  z-index 1000
+
+.arrow
+  position absolute
+  border-width 1u
+  border-style solid
+  border-color transparent
+
+  &.left
+    transform rotate(-90deg)
+
+  &.right
+    transform rotate(90deg)
+
+  &.bottom
+    transform rotate(180deg)

package/index.d.ts

@@ -0,0 +1,46 @@
+/* eslint-disable */
+// DO NOT MODIFY THIS FILE - IT IS AUTOMATICALLY GENERATED ON COMMITS.
+
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type AbstractPopoverAttachment as Attachment, type AbstractPopoverPlacement as Placement, type AbstractPopoverPosition as Position } from './constants';
+import './index.cssx.styl';
+export declare const _PropsJsonSchema: {};
+export interface AbstractPopoverProps {
+    /** Additional cssx styleName(s) for the popover root */
+    styleName?: any;
+    /** Custom styles for popover container */
+    style?: StyleProp<ViewStyle>;
+    /** Ref to the anchor element (must support `measure`) */
+    anchorRef: any;
+    /** Show/hide popover */
+    visible?: boolean;
+    /** Primary position @default 'bottom' */
+    position?: Position;
+    /** Attachment relative to anchor @default 'start' */
+    attachment?: Attachment;
+    /** Ordered placements fallback list */
+    placements?: readonly Placement[];
+    /** Show arrow */
+    arrow?: boolean;
+    /** Match popover width to anchor */
+    matchAnchorWidth?: boolean;
+    /** Open animation duration (ms) @default 100 */
+    durationOpen?: number;
+    /** Close animation duration (ms) @default 50 */
+    durationClose?: number;
+    /** Wrap rendered popover node */
+    renderWrapper?: (node: ReactNode) => ReactNode;
+    /** Called right before open animation starts */
+    onRequestOpen?: () => void;
+    /** Called right before close animation starts */
+    onRequestClose?: () => void;
+    /** Called after open animation ends */
+    onOpenComplete?: (finished?: boolean) => void;
+    /** Called after close animation ends */
+    onCloseComplete?: (finished?: boolean) => void;
+    /** Popover content */
+    children?: ReactNode;
+}
+declare const _default: import("react").ComponentType<AbstractPopoverProps>;
+export default _default;

package/index.tsx

@@ -0,0 +1,230 @@
+import { useState, useCallback, useEffect, useRef, useMemo, type ReactNode } from 'react'
+import {
+  Animated,
+  Easing,
+  Dimensions,
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type ViewStyle
+} from 'react-native'
+import { pug, observer } from 'startupjs'
+import { themed } from '@startupjs-ui/core'
+import Portal from '@startupjs-ui/portal'
+import getGeometry, { type PopoverGeometry } from './getGeometry'
+import {
+  PLACEMENTS_ORDER,
+  type AbstractPopoverAttachment as Attachment,
+  type AbstractPopoverPlacement as Placement,
+  type AbstractPopoverPosition as Position
+} from './constants'
+import './index.cssx.styl'
+
+export const _PropsJsonSchema = {/* AbstractPopoverProps */}
+
+export interface AbstractPopoverProps {
+  /** Additional cssx styleName(s) for the popover root */
+  styleName?: any
+  /** Custom styles for popover container */
+  style?: StyleProp<ViewStyle>
+  /** Ref to the anchor element (must support `measure`) */
+  anchorRef: any
+  /** Show/hide popover */
+  visible?: boolean
+  /** Primary position @default 'bottom' */
+  position?: Position
+  /** Attachment relative to anchor @default 'start' */
+  attachment?: Attachment
+  /** Ordered placements fallback list */
+  placements?: readonly Placement[]
+  /** Show arrow */
+  arrow?: boolean
+  /** Match popover width to anchor */
+  matchAnchorWidth?: boolean
+  /** Open animation duration (ms) @default 100 */
+  durationOpen?: number
+  /** Close animation duration (ms) @default 50 */
+  durationClose?: number
+  /** Wrap rendered popover node */
+  renderWrapper?: (node: ReactNode) => ReactNode
+  /** Called right before open animation starts */
+  onRequestOpen?: () => void
+  /** Called right before close animation starts */
+  onRequestClose?: () => void
+  /** Called after open animation ends */
+  onOpenComplete?: (finished?: boolean) => void
+  /** Called after close animation ends */
+  onCloseComplete?: (finished?: boolean) => void
+  /** Popover content */
+  children?: ReactNode
+}
+
+function AbstractPopover ({
+  visible: visibleProp,
+  onCloseComplete,
+  position = 'bottom',
+  attachment = 'start',
+  placements = PLACEMENTS_ORDER,
+  arrow = false,
+  matchAnchorWidth = false,
+  durationOpen = 100,
+  durationClose = 50,
+  ...props
+}: AbstractPopoverProps): ReactNode {
+  const [visible, setVisible] = useState(false)
+
+  useEffect(() => {
+    if (visibleProp) setVisible(true)
+  }, [visibleProp])
+
+  const handleCloseComplete = useCallback((finished?: boolean) => {
+    setVisible(false)
+    onCloseComplete?.(finished)
+  }, [onCloseComplete])
+
+  if (!visible) return null
+
+  return pug`
+    Tether(
+      ...props
+      visible=visibleProp
+      position=position
+      attachment=attachment
+      placements=placements
+      arrow=arrow
+      matchAnchorWidth=matchAnchorWidth
+      durationOpen=durationOpen
+      durationClose=durationClose
+      onCloseComplete=handleCloseComplete
+    )
+  `
+}
+
+const Tether = observer(function TetherComponent ({
+  styleName,
+  style,
+  anchorRef,
+  visible,
+  position = 'bottom',
+  attachment = 'start',
+  // IDEA: Is this property is redundant?
+  // We can always find a better position if the specified position does not fit
+  // Also we can use the same logic like in tether.io
+  placements = PLACEMENTS_ORDER,
+  arrow = false,
+  matchAnchorWidth = false,
+  durationOpen = 100,
+  durationClose = 50,
+  renderWrapper,
+  onRequestOpen,
+  onRequestClose,
+  onOpenComplete,
+  onCloseComplete,
+  children
+}: AbstractPopoverProps): ReactNode {
+  const flattenedStyle = StyleSheet.flatten(style) as ViewStyle | undefined
+  if (!renderWrapper) renderWrapper = (node): ReactNode => node
+
+  const [geometry, setGeometry] = useState<PopoverGeometry>()
+  const fadeAnim = useRef(new Animated.Value(0)).current
+  const dimensions = useMemo(() => ({
+    width: Dimensions.get('window').width,
+    height: Dimensions.get('window').height
+  }), [])
+
+  const animateIn = useCallback(() => {
+    onRequestOpen?.()
+
+    Animated.parallel([
+      Animated.timing(fadeAnim, {
+        toValue: 1,
+        duration: durationOpen,
+        easing: Easing.linear,
+        useNativeDriver: true
+      })
+    ]).start(({ finished }) => {
+      onOpenComplete?.(finished)
+    })
+  }, [durationOpen, fadeAnim, onOpenComplete, onRequestOpen])
+
+  const animateOut = useCallback(() => {
+    onRequestClose?.()
+
+    Animated.timing(fadeAnim, {
+      toValue: 0,
+      duration: durationClose,
+      easing: Easing.linear,
+      useNativeDriver: true
+    }).start(({ finished }) => {
+      onCloseComplete?.(finished)
+    })
+  }, [durationClose, fadeAnim, onCloseComplete, onRequestClose])
+
+  useEffect(() => {
+    if (!geometry) return
+    if (visible) animateIn()
+    else animateOut()
+  }, [animateIn, animateOut, geometry, visible])
+
+  const calculateGeometry = useCallback(({ nativeEvent }: LayoutChangeEvent) => {
+    // IDEA: we can pass measures to this component
+    // instead of passing ref for the measurement
+    // Also, add property that will manage where popover should appear
+    // in portal or in at the place where component is called
+    // maybe use PortalProvider to render it in the place where component is called
+    anchorRef?.current?.measure?.((x: number, y: number, width: number, height: number, pageX: number, pageY: number) => {
+      // IDEA: rewrite getGeometry in future
+      // we can make geometry behaviout like in tether.js
+      const geometry = getGeometry({
+        placement: `${position}-${attachment}` as Placement,
+        placements,
+        arrow,
+        matchAnchorWidth,
+        dimensions,
+        tetherMeasures: nativeEvent.layout,
+        anchorMeasures: { x, y, width, height, pageX, pageY }
+      })
+      setGeometry(geometry)
+    })
+  }, [anchorRef, arrow, attachment, dimensions, matchAnchorWidth, placements, position])
+
+  // WORKAROUND
+  // the minimum height fixes an issue where the 'onLayout' does not trigger
+  // when children are undefined or have no size.
+  const rootStyle: any = {
+    top: geometry ? geometry.top : -99999,
+    left: geometry ? geometry.left : -99999,
+    opacity: fadeAnim,
+    minHeight: 1
+  }
+
+  if (geometry) {
+    rootStyle.width = geometry.width
+  }
+
+  const popover = pug`
+    Animated.View.root(
+      style=[flattenedStyle, rootStyle]
+      styleName=styleName
+      onLayout=calculateGeometry
+    )
+      if arrow && !!geometry
+        View.arrow(
+          style={
+            borderTopColor: flattenedStyle?.backgroundColor,
+            left: geometry.arrowLeft,
+            top: geometry.arrowTop
+          }
+          styleName=[geometry.position]
+        )
+      = children
+  `
+
+  return pug`
+    Portal
+      = renderWrapper(popover)
+  `
+})
+
+export default observer(themed('AbstractPopover', AbstractPopover))

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@startupjs-ui/abstract-popover",
+  "version": "0.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.tsx",
+  "types": "index.d.ts",
+  "type": "module",
+  "dependencies": {
+    "@startupjs-ui/core": "^0.1.3",
+    "@startupjs-ui/portal": "^0.1.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "startupjs": "*"
+  },
+  "gitHead": "fd964ebc3892d3dd0a6c85438c0af619cc50c3f0"
+}