@startupjs-ui/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/popover
+
+
+
+
+
+## [0.1.2](https://github.com/startupjs/startupjs-ui/compare/v0.1.1...v0.1.2) (2025-12-29)
+
+
+### Features
+
+* 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))
+* **popover:** refactor Popover component ([d43cda5](https://github.com/startupjs/startupjs-ui/commit/d43cda52d95f047bc916a7b42a388e3148513fc3))

package/README.mdx

@@ -0,0 +1,127 @@
+import { useState } from 'react'
+import { Sandbox } from '@startupjs-ui/docs'
+import { faUserCircle } from '@fortawesome/free-solid-svg-icons'
+import Popover, { _PropsJsonSchema as PopoverPropsJsonSchema } from './index'
+import Icon from '@startupjs-ui/icon'
+import Button from '@startupjs-ui/button'
+import Div from '@startupjs-ui/div'
+import Span from '@startupjs-ui/span'
+
+# Popover
+
+Pop-up window for displaying hidden content, linked in some way to a specific element on the page and becomes visible when you click on this.
+
+```jsx
+import { Popover } from 'startupjs-ui'
+```
+
+## Initialization
+
+Before use you need to configure [Portal](/docs/components/Portal)
+
+## Simple example
+
+- `children` (ReactNode): anchor (visible part)
+- `renderContent` (function: ReactNode): function returns hidden part
+
+```jsx example
+const [visible, setVisible] = useState(false)
+
+function renderContent () {
+  return (
+    <Div style={{ padding: 10 }}>
+      <Span>Content</Span>
+    </Div>
+  )
+}
+
+return (
+  <Popover
+    visible={visible}
+    onChange={setVisible}
+    renderContent={renderContent}
+  >
+    <Icon icon={faUserCircle} size='xl' />
+  </Popover>
+)
+```
+
+## Position
+
+- `position` (string - 'top', 'bottom', 'left', 'right'): position relative to the visible part
+- `attachment` (string - 'start', 'center', 'end'): optional parameter for offset
+- `placements` (array): what positions can be used for auto-fix
+
+```jsx example
+const [visible, setVisible] = useState(false)
+
+function renderContent () {
+  return (
+    <Div style={{ padding: 10 }}>
+      <Span>Content</Span>
+    </Div>
+  )
+}
+
+return (
+  <Popover
+    visible={visible}
+    onChange={setVisible}
+    position='top'
+    attachment='center'
+    renderContent={renderContent}
+  >
+    <Button>Open</Button>
+  </Popover>
+)
+```
+
+## Stylization
+
+- `style`: styles for the anchor wrapper
+- `attachmentStyle`: styles for the popover container
+- `overlayStyle`: dismiss overlay styles
+- `arrow` (boolean): show an arrow
+- `matchAnchorWidth` (boolean): the width of the popover is equal to the width of the anchor
+
+```jsx example
+const [visible, setVisible] = useState(false)
+
+function renderContent () {
+  return (
+    <Span style={{ color: '#fff' }}>Content</Span>
+  )
+}
+
+return (
+  <Popover
+    visible={visible}
+    onChange={setVisible}
+    arrow
+    matchAnchorWidth
+    attachment='center'
+    renderContent={renderContent}
+    attachmentStyle={{ backgroundColor: '#333', padding: 10 }}
+  >
+    <Button>Open</Button>
+  </Popover>
+)
+```
+
+## Extra options
+
+- `durationOpen` (number): animation time on opening
+- `durationClose` (number): animation time on close
+
+## Sandbox
+
+<Sandbox
+  Component={Popover}
+  propsJsonSchema={PopoverPropsJsonSchema}
+  props={{
+    visible: false,
+    onChange: () => {},
+    renderContent: () => <Div style={{ padding: 10 }}><Span>Content</Span></Div>,
+    children: <Span>Anchor</Span>
+  }}
+/>

package/index.cssx.styl

@@ -0,0 +1,14 @@
+.root
+.overlay
+  position absolute
+  top 0
+  left 0
+  right 0
+  bottom 0
+
+.attachment
+  background-color var(--color-bg-main-strong)
+  radius()
+  shadow(3)
+  overflow hidden
+

package/index.d.ts

@@ -0,0 +1,36 @@
+/* eslint-disable */
+// DO NOT MODIFY THIS FILE - IT IS AUTOMATICALLY GENERATED ON COMMITS.
+
+import { type ReactNode, type RefObject } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type AbstractPopoverProps } from '@startupjs-ui/abstract-popover';
+import './index.cssx.styl';
+export declare const _PropsJsonSchema: {};
+export interface PopoverProps extends Omit<AbstractPopoverProps, 'anchorRef' | 'children' | 'style' | 'visible'> {
+    /** Ref to control popover programmatically */
+    ref?: RefObject<PopoverRef>;
+    /** Custom styles for the anchor wrapper */
+    style?: StyleProp<ViewStyle>;
+    /** Custom styles for the popover container */
+    attachmentStyle?: StyleProp<ViewStyle>;
+    /** Custom styles for the dismiss overlay */
+    overlayStyle?: StyleProp<ViewStyle>;
+    /** Controlled visibility flag */
+    visible?: boolean;
+    /** Two-way binding value controlling visibility */
+    $visible?: any;
+    /** Called when visibility should change */
+    onChange?: (visible: boolean) => void;
+    /** Anchor content */
+    children?: ReactNode;
+    /** Render function for popover content */
+    renderContent?: () => ReactNode;
+}
+export interface PopoverRef {
+    /** Open the popover */
+    open: () => void;
+    /** Close the popover */
+    close: () => void;
+}
+declare const _default: import("react").ComponentType<PopoverProps>;
+export default _default;

package/index.tsx

@@ -0,0 +1,113 @@
+import { useMemo, useRef, useCallback, useImperativeHandle, type ReactNode, type RefObject } from 'react'
+import { View, TouchableWithoutFeedback, type StyleProp, type ViewStyle } from 'react-native'
+import { pug, observer, useBind, $ } from 'startupjs'
+import { themed } from '@startupjs-ui/core'
+import AbstractPopover, { type AbstractPopoverProps } from '@startupjs-ui/abstract-popover'
+import Div from '@startupjs-ui/div'
+import './index.cssx.styl'
+
+export const _PropsJsonSchema = {/* PopoverProps */}
+
+export interface PopoverProps extends Omit<AbstractPopoverProps, 'anchorRef' | 'children' | 'style' | 'visible'> {
+  /** Ref to control popover programmatically */
+  ref?: RefObject<PopoverRef>
+  /** Custom styles for the anchor wrapper */
+  style?: StyleProp<ViewStyle>
+  /** Custom styles for the popover container */
+  attachmentStyle?: StyleProp<ViewStyle>
+  /** Custom styles for the dismiss overlay */
+  overlayStyle?: StyleProp<ViewStyle>
+  /** Controlled visibility flag */
+  visible?: boolean
+  /** Two-way binding value controlling visibility */
+  $visible?: any
+  /** Called when visibility should change */
+  onChange?: (visible: boolean) => void
+  /** Anchor content */
+  children?: ReactNode
+  /** Render function for popover content */
+  renderContent?: () => ReactNode
+}
+
+export interface PopoverRef {
+  /** Open the popover */
+  open: () => void
+  /** Close the popover */
+  close: () => void
+}
+
+function Popover ({
+  style,
+  attachmentStyle,
+  visible,
+  $visible,
+  children,
+  renderContent,
+  onChange,
+  renderWrapper,
+  overlayStyle,
+  ref,
+  ...props
+}: PopoverProps): ReactNode {
+  const anchorRef = useRef<any>(null)
+
+  const isUncontrolled = useMemo(() => {
+    const isUsedViaTwoWayDataBinding = typeof $visible !== 'undefined'
+    const isUsedViaState = typeof onChange === 'function'
+    return !(isUsedViaTwoWayDataBinding || isUsedViaState)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const $internalVisible = $(false)
+  const $effectiveVisible = isUncontrolled ? $internalVisible : $visible
+
+  ;({ visible, onChange } = useBind({ visible, $visible: $effectiveVisible, onChange }) as any)
+
+  const handleChange = useCallback((nextVisible: boolean) => {
+    if (typeof onChange === 'function') {
+      onChange(nextVisible)
+      return
+    }
+    if ($effectiveVisible) {
+      $effectiveVisible.set(nextVisible)
+      return
+    }
+    $internalVisible.set(nextVisible)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  useImperativeHandle(ref, () => ({
+    open: () => { handleChange(true) },
+    close: () => { handleChange(false) }
+  }), [handleChange])
+
+  const setVisibleTrue = useCallback(() => { handleChange(true) }, [handleChange])
+  const setVisibleFalse = useCallback(() => { handleChange(false) }, [handleChange])
+
+  const renderOverlayWrapper = (node: ReactNode): ReactNode => {
+    const wrappedNode = renderWrapper ? renderWrapper(node) : node
+    return pug`
+      View.root
+        TouchableWithoutFeedback(onPress=setVisibleFalse)
+          View.overlay(style=overlayStyle)
+        = wrappedNode
+    `
+  }
+
+  return pug`
+    Div(
+      style=style
+      ref=anchorRef
+      onPress=isUncontrolled ? null : setVisibleTrue
+    )= children
+    AbstractPopover.attachment(
+      ...props
+      visible=visible
+      style=[attachmentStyle]
+      anchorRef=anchorRef
+      renderWrapper=renderOverlayWrapper
+    )= renderContent && renderContent()
+  `
+}
+
+export default observer(themed('Popover', Popover))

package/package.json

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