fluent-styles 1.54.0 → 1.55.0

package/src/popup/helpers.ts

@@ -0,0 +1,123 @@
+import { Dimensions } from 'react-native'
+import type { ViewStyle } from 'react-native'
+
+import type { PopupAnimation, PopupPosition } from './interface'
+
+// ─── Resolve default animation per position ───────────────────────────────────
+
+export function resolveAnimation(
+  animation: PopupAnimation | undefined,
+  position:  PopupPosition,
+): PopupAnimation {
+  if (animation) return animation
+  return position === 'center' ? 'scale' : 'slide'
+}
+
+// ─── Animated value: "hidden" end-state ───────────────────────────────────────
+// For slide: off-screen offset (px).  For fade/scale: target opacity/scale.
+
+export function hiddenValue(
+  animation: PopupAnimation,
+  position:  PopupPosition,
+): number {
+  if (animation === 'fade')  return 0     // opacity 0
+  if (animation === 'scale') return 0.88  // scale 0.88
+  if (animation === 'none')  return 0
+
+  // slide — return the off-screen offset in the axis of motion
+  const { width, height } = Dimensions.get('window')
+  switch (position) {
+    case 'top':    return -height
+    case 'bottom': return height
+    case 'left':   return -width
+    case 'right':  return width
+    default:       return 0
+  }
+}
+
+export function visibleValue(animation: PopupAnimation): number {
+  if (animation === 'fade')  return 1
+  if (animation === 'scale') return 1
+  return 0   // slide: 0 offset = on-screen
+}
+
+// ─── Build animated style from current value ──────────────────────────────────
+
+export function animatedStyle(
+  animation: PopupAnimation,
+  position:  PopupPosition,
+  value:     any,          // Animated.Value
+): ViewStyle {
+  switch (animation) {
+    case 'fade':
+      return { opacity: value }
+
+    case 'scale':
+      return {
+        opacity:   value,   // cross-fade opacity in parallel
+        transform: [{ scale: value }],
+      }
+
+    case 'slide': {
+      const isY = position === 'top' || position === 'bottom'
+      return {
+        transform: [
+          isY ? { translateY: value } : { translateX: value },
+        ],
+      }
+    }
+
+    case 'none':
+    default:
+      return {}
+  }
+}
+
+// ─── Border radius: round the corners facing the screen interior ──────────────
+
+export function getBorderRadius(
+  position: PopupPosition,
+  round:    boolean,
+  radius:   number,
+): ViewStyle {
+  if (!round || position === 'center') return {}
+
+  const r = radius
+  switch (position) {
+    case 'bottom':
+      return { borderTopLeftRadius: r, borderTopRightRadius: r }
+    case 'top':
+      return { borderBottomLeftRadius: r, borderBottomRightRadius: r }
+    case 'left':
+      return { borderTopRightRadius: r, borderBottomRightRadius: r }
+    case 'right':
+      return { borderTopLeftRadius: r, borderBottomLeftRadius: r }
+    default:
+      return { borderRadius: r }
+  }
+}
+
+// ─── Absolute position style for the popup surface ────────────────────────────
+
+export function getPositionStyle(position: PopupPosition): ViewStyle {
+  const fill: ViewStyle = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }
+
+  switch (position) {
+    case 'bottom':
+      return { position: 'absolute', left: 0, right: 0, bottom: 0 }
+    case 'top':
+      return { position: 'absolute', left: 0, right: 0, top: 0 }
+    case 'left':
+      return { position: 'absolute', top: 0, left: 0, bottom: 0 }
+    case 'right':
+      return { position: 'absolute', top: 0, right: 0, bottom: 0 }
+    case 'center':
+      return {
+        ...fill,
+        alignItems:     'center',
+        justifyContent: 'center',
+      }
+    default:
+      return fill
+  }
+}

package/src/popup/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @module Popup
+ *
+ * ─── Bottom sheet (default) ──────────────────────────────────────────────────
+ * ```tsx
+ * import { Popup } from './popup'
+ *
+ * <Popup visible={open} onClose={() => setOpen(false)} title="Options" showClose>
+ *   <Text>Content here</Text>
+ * </Popup>
+ * ```
+ *
+ * ─── Positions ───────────────────────────────────────────────────────────────
+ * ```tsx
+ * <Popup visible={open} position="top"    onClose={close}>…</Popup>
+ * <Popup visible={open} position="left"   onClose={close}>…</Popup>
+ * <Popup visible={open} position="right"  onClose={close}>…</Popup>
+ * <Popup visible={open} position="center" onClose={close}>…</Popup>
+ * ```
+ *
+ * ─── Animation styles ────────────────────────────────────────────────────────
+ * ```tsx
+ * <Popup animation="slide" />  // default for side positions
+ * <Popup animation="scale" />  // default for center
+ * <Popup animation="fade"  />
+ * <Popup animation="none"  />  // instant
+ * ```
+ *
+ * ─── Spring physics ──────────────────────────────────────────────────────────
+ * ```tsx
+ * <Popup spring={{ damping: 20, stiffness: 300 }}>…</Popup>
+ * ```
+ *
+ * ─── Color overrides ─────────────────────────────────────────────────────────
+ * ```tsx
+ * <Popup colors={{ background: '#0f172a', headerTitle: '#f8fafc' }}>…</Popup>
+ * ```
+ */
+
+export { Popup }                                    from './Popup'
+export type { PopupProps, PopupColors,
+              PopupPosition, PopupAnimation }        from './interface'
+export { POPUP_COLORS_LIGHT, POPUP_COLORS_DARK }    from './interface'
+export { getBorderRadius, getPositionStyle,
+         resolveAnimation, animatedStyle }           from './helpers'

package/src/popup/interface.ts

@@ -0,0 +1,178 @@
+import type { PropsWithChildren, ReactNode } from 'react'
+import type {
+  StyleProp,
+  ViewStyle,
+  TextStyle,
+  ColorValue,
+  ViewProps,
+} from 'react-native'
+
+// ─── Position ─────────────────────────────────────────────────────────────────
+
+export type PopupPosition = 'top' | 'bottom' | 'left' | 'right' | 'center'
+
+// ─── Animation style ──────────────────────────────────────────────────────────
+
+/**
+ * Controls how the popup enters/exits.
+ * - `'slide'`  — slides in from the edge (default for side positions)
+ * - `'fade'`   — opacity only
+ * - `'scale'`  — scale from center (good for center position)
+ * - `'none'`   — instant, no animation
+ */
+export type PopupAnimation = 'slide' | 'fade' | 'scale' | 'none'
+
+// ─── Color tokens ─────────────────────────────────────────────────────────────
+
+export type PopupColors = {
+  /** Popup surface background. */
+  background:      string
+  /** Semi-transparent overlay behind the popup. */
+  overlay:         string
+  /** Handle pill (bottom sheet). */
+  handle:          string
+  /** Header title text. */
+  headerTitle:     string
+  /** Header subtitle text. */
+  headerSubtitle:  string
+  /** Header border / divider. */
+  headerBorder:    string
+  /** Close button icon colour. */
+  closeIcon:       string
+  /** Close button background. */
+  closeIconBg:     string
+}
+
+export const POPUP_COLORS_LIGHT: PopupColors = {
+  background:     '#ffffff',
+  overlay:        'rgba(0,0,0,0.5)',
+  handle:         '#d4d4d8',
+  headerTitle:    '#18181b',
+  headerSubtitle: '#71717a',
+  headerBorder:   '#f4f4f5',
+  closeIcon:      '#71717a',
+  closeIconBg:    '#f4f4f5',
+}
+
+export const POPUP_COLORS_DARK: PopupColors = {
+  background:     '#1c1c1e',
+  overlay:        'rgba(0,0,0,0.7)',
+  handle:         '#3f3f46',
+  headerTitle:    '#f4f4f5',
+  headerSubtitle: '#a1a1aa',
+  headerBorder:   '#27272a',
+  closeIcon:      '#a1a1aa',
+  closeIconBg:    '#27272a',
+}
+
+// ─── Common lifecycle callbacks ────────────────────────────────────────────────
+
+export type PopupLifecycle = {
+  /** Fires immediately when visibility changes to true. */
+  onOpen?:   () => void
+  /** Fires after the open animation completes. */
+  onOpened?: () => void
+  /** Fires immediately when visibility changes to false. */
+  onClose?:  () => void
+  /** Fires after the close animation completes. */
+  onClosed?: () => void
+}
+
+// ─── Popup props ──────────────────────────────────────────────────────────────
+
+export interface PopupProps extends PropsWithChildren<{}>, PopupLifecycle {
+
+  // ── Visibility ────────────────────────────────────────────────────────────
+
+  /** Whether the popup is visible. */
+  visible: boolean
+
+  // ── Overlay ───────────────────────────────────────────────────────────────
+
+  /** Show a backdrop overlay. @default true */
+  overlay?: boolean
+  /** Custom overlay colour. Falls back to `colors.overlay`. */
+  overlayColor?: ColorValue
+  /** Close the popup when the overlay is pressed. @default true */
+  closeOnPressOverlay?: boolean
+  /** Called when the overlay is pressed. */
+  onPressOverlay?: () => void
+
+  // ── Position & animation ──────────────────────────────────────────────────
+
+  /** Where the popup enters from. @default 'bottom' */
+  position?: PopupPosition
+
+  /**
+   * Animation style.
+   * Defaults: `slide` for side positions, `scale` for center.
+   */
+  animation?: PopupAnimation
+
+  /** Animation duration in ms. @default 280 */
+  duration?: number
+
+  /**
+   * Spring physics for slide/scale animations.
+   * When set, overrides `duration` for the open animation.
+   */
+  spring?: {
+    damping:   number
+    stiffness: number
+    mass?:     number
+  }
+
+  // ── Shape ─────────────────────────────────────────────────────────────────
+
+  /** Round the corners facing the interior of the screen. @default true */
+  round?: boolean
+
+  /** Border radius value when `round` is true. @default 20 */
+  roundRadius?: number
+
+  // ── Safe area ─────────────────────────────────────────────────────────────
+
+  /** Add padding for the bottom safe area (notch / home bar). @default false */
+  safeAreaBottom?: boolean
+  /** Add padding for the top safe area (status bar). @default false */
+  safeAreaTop?: boolean
+
+  // ── Render strategy ───────────────────────────────────────────────────────
+
+  /** Only mount children after the first open. @default true */
+  lazyRender?: boolean
+  /** Unmount children when closed (resets to lazy state). @default false */
+  destroyOnClose?: boolean
+
+  // ── Header ────────────────────────────────────────────────────────────────
+
+  /** Optional header title. Enables the built-in header. */
+  title?: ReactNode
+  /** Optional subtitle rendered below the title. */
+  subtitle?: ReactNode
+  /** Show a drag handle pill above the header. @default true for bottom */
+  showHandle?: boolean
+  /** Show a close (×) button in the header. @default false */
+  showClose?: boolean
+  /** Called when the close button is pressed. */
+  onClose?: () => void
+
+  // ── Style overrides ───────────────────────────────────────────────────────
+
+  style?:         StyleProp<ViewStyle>
+  overlayStyle?:  StyleProp<ViewStyle>
+  headerStyle?:   StyleProp<ViewStyle>
+  titleStyle?:    StyleProp<TextStyle>
+  subtitleStyle?: StyleProp<TextStyle>
+
+  // ── Theming ───────────────────────────────────────────────────────────────
+
+  colors?: Partial<PopupColors>
+
+  // ── Android back button ───────────────────────────────────────────────────
+
+  /** Return true to handle the back button (Android). */
+  onRequestClose?: () => boolean
+
+  testID?: ViewProps['testID']
+}

package/src/portal/GlobalPortalProvider.tsx

@@ -0,0 +1,63 @@
+import React, { useEffect, useState } from 'react'
+import { portal } from './PortalInstance'
+import { PortalRenderer } from './PortalRenderer'
+import type { PortalNode } from './types'
+
+/**
+ * Subscribes to the global `portal` singleton and renders whatever portals
+ * it currently holds.
+ *
+ * ### Usage
+ * Wrap your app root (or the root of the navigable area) with this provider.
+ * You can then call `portal.show(...)` / `portal.hide(...)` from anywhere —
+ * including non-React code such as navigation helpers or async service
+ * callbacks.
+ *
+ * This component deliberately has **no** React context value; it exists purely
+ * to drive re-renders when the singleton changes.  If you also need the
+ * declarative `usePortal()` hook, use `PortalManager` instead (or nest both).
+ *
+ * @example
+ * ```tsx
+ * // App root
+ * export default function App() {
+ *   return (
+ *     <GlobalPortalProvider>
+ *       <Navigation />
+ *     </GlobalPortalProvider>
+ *   )
+ * }
+ *
+ * // Anywhere – including outside React
+ * import { portal } from '@/portal'
+ *
+ * function showNetworkError() {
+ *   const id = portal.show(
+ *     <ErrorBanner message="No internet connection" />,
+ *     { position: 'top', backdrop: false },
+ *   )
+ *   setTimeout(() => portal.hide(id), 4000)
+ * }
+ * ```
+ */
+
+type Props = { children: React.ReactNode }
+
+export const GlobalPortalProvider: React.FC<Props> = ({ children }) => {
+  const [portals, setPortals] = useState<PortalNode[]>(() => portal.getPortals())
+
+  useEffect(() => {
+    // Sync state whenever the singleton changes.
+    const unsubscribe = portal.subscribe(() => {
+      setPortals(portal.getPortals())
+    })
+    return unsubscribe
+  }, [])
+
+  return (
+    <>
+      {children}
+      <PortalRenderer portals={portals} />
+    </>
+  )
+}

package/src/portal/PortalContext.ts

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react'
+import type { PortalContextType } from './types'
+
+/**
+ * React context that carries the declarative mount / update / unmount API.
+ * Consumed by the `usePortal` hook below and provided by `PortalManager`.
+ */
+export const PortalContext = createContext<PortalContextType | null>(null)
+
+/**
+ * Returns the portal control API from the nearest `PortalManager` ancestor.
+ *
+ * @example
+ * ```tsx
+ * const { mount, unmount } = usePortal()
+ *
+ * const handleOpen = () => {
+ *   const id = mount(<MyModal />, { backdrop: true, position: 'center' })
+ *   // Later:
+ *   unmount(id)
+ * }
+ * ```
+ *
+ * @throws If called outside a `PortalManager` tree.
+ */
+export function usePortal(): PortalContextType {
+  const context = useContext(PortalContext)
+
+  if (!context) {
+    throw new Error(
+      '[Portal] `usePortal` must be called inside a `PortalManager` (or `GlobalPortalProvider`) tree. ' +
+        'Ensure your app root is wrapped with one of those providers.',
+    )
+  }
+
+  return context
+}

package/src/portal/PortalInstance.ts

@@ -0,0 +1,118 @@
+import type React from 'react'
+import type { PortalNode, PortalOptions } from './types'
+
+type Listener = () => void
+
+/**
+ * Imperative, framework-agnostic portal registry.
+ *
+ * `PortalInstance` holds the source-of-truth for all portals that are managed
+ * outside the React tree (e.g. from plain TypeScript helpers, navigation
+ * handlers, or third-party libraries).  React components subscribe to changes
+ * via `subscribe()` and re-render when the list changes.
+ *
+ * The exported `portal` singleton is the recommended way to interact with this
+ * class.  Only create additional instances if you need isolated portal scopes
+ * (e.g. in tests or multi-window environments).
+ *
+ * @example
+ * ```ts
+ * // Show
+ * const id = portal.show(<Toast message="Saved!" />, { position: 'bottom' })
+ *
+ * // Later update the same portal without closing it
+ * portal.update(id, <Toast message="Updated!" />)
+ *
+ * // Dismiss
+ * portal.hide(id)
+ * ```
+ */
+export class PortalInstance {
+  private nextId = 10_000
+  private portals = new Map<number, PortalNode>()
+  private listeners = new Set<Listener>()
+
+  // ─── Subscription ─────────────────────────────────────────────────────────
+
+  /**
+   * Registers a change listener. Returns an unsubscribe function.
+   *
+   * Consumers (e.g. `GlobalPortalProvider`) call this once on mount and
+   * invoke the returned cleanup on unmount.
+   */
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  private notify(): void {
+    this.listeners.forEach(fn => fn())
+  }
+
+  // ─── Read ─────────────────────────────────────────────────────────────────
+
+  /** Returns a stable snapshot of all currently registered portals. */
+  getPortals(): PortalNode[] {
+    return Array.from(this.portals.values())
+  }
+
+  // ─── Write ────────────────────────────────────────────────────────────────
+
+  /**
+   * Registers a new portal and triggers a re-render in all subscribers.
+   *
+   * @returns The numeric `id` assigned to this portal – hold onto it to
+   *          call `update` or `hide` later.
+   */
+  show(children: React.ReactNode, options: PortalOptions = {}): number {
+    const id = this.nextId++
+    this.portals.set(id, { id, children, options })
+    this.notify()
+    return id
+  }
+
+  /**
+   * Replaces the content / options of an existing portal in-place.
+   * If `id` is not found, the call is a silent no-op (safe to call
+   * unconditionally inside cleanup paths).
+   */
+  update(id: number, children: React.ReactNode, options?: PortalOptions): void {
+    const existing = this.portals.get(id)
+    if (!existing) return
+
+    this.portals.set(id, {
+      ...existing,
+      children,
+      options: options ?? existing.options,
+    })
+    this.notify()
+  }
+
+  /**
+   * Removes a portal and triggers a re-render.
+   * Safe to call with an `id` that has already been hidden.
+   */
+  hide(id: number): void {
+    if (this.portals.delete(id)) {
+      this.notify()
+    }
+  }
+
+  /**
+   * Removes **all** registered portals at once.
+   * Useful for screen transitions or hard resets.
+   */
+  hideAll(): void {
+    if (this.portals.size === 0) return
+    this.portals.clear()
+    this.notify()
+  }
+}
+
+/**
+ * Application-wide portal singleton.
+ * Import and use this wherever you need imperative portal control.
+ */
+export const portal = new PortalInstance()

package/src/portal/PortalManager.tsx

@@ -0,0 +1,84 @@
+import React, { useCallback, useState } from 'react'
+import { PortalContext } from './PortalContext'
+import { PortalRenderer } from './PortalRenderer'
+import type { PortalNode, PortalOptions } from './types'
+
+/**
+ * Provides the **declarative** portal API to its React subtree via context.
+ *
+ * Place `PortalManager` at (or near) the root of your component tree so that
+ * any descendant can call `usePortal()` to imperatively mount floating UI.
+ *
+ * ### When to use `PortalManager` vs `GlobalPortalProvider`
+ * | Scenario | Recommended provider |
+ * |---|---|
+ * | React-component consumers using `usePortal()` | `PortalManager` |
+ * | Non-React code / navigation handlers | `GlobalPortalProvider` |
+ * | Both | Wrap with `GlobalPortalProvider`; it re-exports the hook too |
+ *
+ * @example
+ * ```tsx
+ * // App root
+ * export default function App() {
+ *   return (
+ *     <PortalManager>
+ *       <Navigation />
+ *     </PortalManager>
+ *   )
+ * }
+ *
+ * // Somewhere deep in the tree
+ * function MyScreen() {
+ *   const { mount, unmount } = usePortal()
+ *   const idRef = useRef<number>()
+ *
+ *   const open = () => {
+ *     idRef.current = mount(<Modal />, { backdrop: true })
+ *   }
+ *   const close = () => idRef.current && unmount(idRef.current)
+ *
+ *   return <Button onPress={open} title="Open" />
+ * }
+ * ```
+ */
+
+let _nextId = 0
+
+type Props = { children: React.ReactNode }
+
+export const PortalManager: React.FC<Props> = ({ children }) => {
+  const [portals, setPortals] = useState<PortalNode[]>([])
+
+  const mount = useCallback(
+    (node: React.ReactNode, options: PortalOptions = {}): number => {
+      const id = _nextId++
+      setPortals(prev => [...prev, { id, children: node, options }])
+      return id
+    },
+    [],
+  )
+
+  const update = useCallback(
+    (id: number, node: React.ReactNode, options?: PortalOptions): void => {
+      setPortals(prev =>
+        prev.map(portal =>
+          portal.id === id
+            ? { ...portal, children: node, options: options ?? portal.options }
+            : portal,
+        ),
+      )
+    },
+    [],
+  )
+
+  const unmount = useCallback((id: number): void => {
+    setPortals(prev => prev.filter(portal => portal.id !== id))
+  }, [])
+
+  return (
+    <PortalContext.Provider value={{ mount, update, unmount }}>
+      {children}
+      <PortalRenderer portals={portals} />
+    </PortalContext.Provider>
+  )
+}