@butternutbox/pawprint-native 0.10.10 → 0.11.0

package/src/components/molecules/StackedNotifications/StackedNotifications.test.tsx

@@ -0,0 +1,202 @@
+import React from "react"
+import { screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+import { renderWithTheme } from "../../../test-utils"
+import { StackedNotifications } from "./StackedNotifications"
+import type { StackedNotificationItem } from "./StackedNotifications"
+
+const A: StackedNotificationItem = {
+  id: "a",
+  type: "info",
+  message: "First notification"
+}
+const B: StackedNotificationItem = {
+  id: "b",
+  type: "warning",
+  message: "Second notification"
+}
+const C: StackedNotificationItem = {
+  id: "c",
+  type: "info",
+  message: "Third notification"
+}
+
+describe("StackedNotifications", () => {
+  describe("ordering (LIFO, front is interactive)", () => {
+    it("shows the most recent item as the front, interactive card", () => {
+      renderWithTheme(<StackedNotifications items={[A, B]} />)
+
+      expect(screen.getByRole("alert")).toHaveTextContent("Second notification")
+    })
+
+    it("renders exactly one interactive notification when several are queued", () => {
+      renderWithTheme(<StackedNotifications items={[A, B, C]} />)
+
+      expect(screen.getAllByRole("alert")).toHaveLength(1)
+      expect(screen.getByText("Third notification")).toBeInTheDocument()
+    })
+
+    it("renders nothing when there are no items", () => {
+      renderWithTheme(<StackedNotifications items={[]} />)
+
+      expect(screen.queryByRole("alert")).not.toBeInTheDocument()
+    })
+  })
+
+  describe("peek stack (up to 2 behind the front card)", () => {
+    it("renders the front card plus one peek when 2 items are queued", () => {
+      renderWithTheme(<StackedNotifications items={[A, B]} />)
+
+      expect(screen.getByRole("alert")).toBeInTheDocument()
+      expect(screen.getByText("Second notification")).toBeInTheDocument()
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+    })
+
+    it("caps peeks at 2 regardless of how many are queued", () => {
+      const D: StackedNotificationItem = {
+        id: "d",
+        type: "warning",
+        message: "Fourth notification"
+      }
+      renderWithTheme(<StackedNotifications items={[A, B, C, D]} />)
+
+      // Front (D) + 2 peeks (C, B) are present; the oldest (A) is not rendered.
+      expect(screen.getByText("Fourth notification")).toBeInTheDocument()
+      expect(screen.getByText("Third notification")).toBeInTheDocument()
+      expect(screen.getByText("Second notification")).toBeInTheDocument()
+      expect(screen.queryByText("First notification")).not.toBeInTheDocument()
+    })
+
+    it("only the front card is exposed as an alert; peeks are hidden from the accessibility tree", () => {
+      renderWithTheme(<StackedNotifications items={[A, B, C]} />)
+
+      expect(screen.getAllByRole("alert")).toHaveLength(1)
+      expect(screen.getByRole("alert")).toHaveTextContent("Third notification")
+    })
+
+    it("only the front card has a close control", () => {
+      renderWithTheme(<StackedNotifications items={[A, B, C]} />)
+
+      expect(
+        screen.getAllByRole("button", { name: "Close notification" })
+      ).toHaveLength(1)
+    })
+
+    it("promotes the next peek to front, revealing a new peek behind it", async () => {
+      const D: StackedNotificationItem = {
+        id: "d",
+        type: "warning",
+        message: "Fourth notification"
+      }
+      const user = userEvent.setup()
+      renderWithTheme(<StackedNotifications items={[A, B, C, D]} />)
+
+      await user.click(
+        screen.getByRole("button", { name: "Close notification" })
+      )
+
+      expect(screen.getByRole("alert")).toHaveTextContent("Third notification")
+      expect(screen.getByText("Second notification")).toBeInTheDocument()
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+      expect(screen.queryByText("Fourth notification")).not.toBeInTheDocument()
+    })
+  })
+
+  describe("variants", () => {
+    it("renders the info variant with its icon", () => {
+      renderWithTheme(<StackedNotifications items={[A]} />)
+
+      expect(screen.getByLabelText("info")).toBeInTheDocument()
+    })
+
+    it("renders the warning variant with its icon", () => {
+      renderWithTheme(<StackedNotifications items={[B]} />)
+
+      expect(screen.getByLabelText("warning")).toBeInTheDocument()
+    })
+  })
+
+  describe("dismissing", () => {
+    it("reveals the next item when the visible one is dismissed", async () => {
+      const user = userEvent.setup()
+      renderWithTheme(<StackedNotifications items={[A, B]} />)
+
+      await user.click(
+        screen.getByRole("button", { name: "Close notification" })
+      )
+
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+      expect(screen.queryByText("Second notification")).not.toBeInTheDocument()
+    })
+
+    it("calls onDismiss with the dismissed item id", async () => {
+      const user = userEvent.setup()
+      const onDismiss = vi.fn()
+      renderWithTheme(
+        <StackedNotifications items={[A, B]} onDismiss={onDismiss} />
+      )
+
+      await user.click(
+        screen.getByRole("button", { name: "Close notification" })
+      )
+
+      expect(onDismiss).toHaveBeenCalledTimes(1)
+      expect(onDismiss).toHaveBeenCalledWith("b")
+    })
+  })
+
+  describe("persistence (no auto-dismiss)", () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+    })
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it("does not dismiss on its own over time", () => {
+      renderWithTheme(<StackedNotifications items={[A]} />)
+
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+      vi.advanceTimersByTime(60000)
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+    })
+  })
+
+  describe("re-raise on reselect", () => {
+    it("keeps the notification until its item is removed", () => {
+      const { rerender } = renderWithTheme(
+        <StackedNotifications items={[A, B]} />
+      )
+
+      // Deselect B — A is revealed.
+      rerender(<StackedNotifications items={[A]} />)
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+      expect(screen.queryByText("Second notification")).not.toBeInTheDocument()
+
+      // Reselect B — it re-raises to the top.
+      rerender(<StackedNotifications items={[A, B]} />)
+      expect(screen.getByText("Second notification")).toBeInTheDocument()
+    })
+
+    it("re-raises a previously dismissed item after deselect then reselect", async () => {
+      const user = userEvent.setup()
+      const { rerender } = renderWithTheme(
+        <StackedNotifications items={[A, B]} />
+      )
+
+      // Dismiss B — A shown, B hidden but still selected.
+      await user.click(
+        screen.getByRole("button", { name: "Close notification" })
+      )
+      expect(screen.getByText("First notification")).toBeInTheDocument()
+
+      // Deselect B (removed from items) then reselect it.
+      rerender(<StackedNotifications items={[A]} />)
+      rerender(<StackedNotifications items={[A, B]} />)
+
+      // The dismissed flag was cleared, so B shows again.
+      expect(screen.getByText("Second notification")).toBeInTheDocument()
+    })
+  })
+})

package/src/components/molecules/StackedNotifications/StackedNotifications.tsx

@@ -0,0 +1,247 @@
+import React from "react"
+import { View, ViewProps } from "react-native"
+import Reanimated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  FadeInDown,
+  FadeOutDown,
+  Easing
+} from "react-native-reanimated"
+import styled from "@emotion/native"
+import { useTheme } from "@emotion/react"
+import { Notification } from "../Notification"
+
+type StackedNotificationType = "info" | "warning"
+
+type StackedNotificationItem = {
+  id: string
+  type: StackedNotificationType
+  message: React.ReactNode
+}
+
+type StackedNotificationsOwnProps = {
+  items: StackedNotificationItem[]
+  onDismiss?: (id: string) => void
+  bottomOffset?: number
+}
+
+export type StackedNotificationsProps = StackedNotificationsOwnProps &
+  Omit<ViewProps, keyof StackedNotificationsOwnProps | "children">
+
+const parseTokenValue = (value: string): number => parseFloat(value)
+
+// Behind the front card, at most this many queued notifications peek out
+// (à la iOS notification grouping) — regardless of how many are queued.
+const PEEK_LAYERS = 2
+
+// Unitless recede per depth level — the reveal distance itself comes from a
+// spacing token (`peekStep`), this only controls the "shrink into the
+// background" feel.
+const SCALE_STEP = 0.06
+const SPRING_CONFIG = { damping: 20, stiffness: 260, mass: 0.5 }
+
+const CARD_ENTERING = FadeInDown.duration(200).easing(Easing.inOut(Easing.quad))
+const CARD_EXITING = FadeOutDown.duration(200)
+
+// Bottom-anchored so scaling never moves a card's bottom edge — only
+// translateY does. That's what makes the peek reveal an exact, constant
+// distance regardless of a card's own message length.
+const CARD_BASE_STYLE = {
+  position: "absolute" as const,
+  bottom: 0,
+  left: 0,
+  right: 0,
+  transformOrigin: "50% 100%"
+}
+
+// Floats over content pinned to the bottom. `box-none` lets touches pass
+// through to the content behind everywhere except on the notification itself,
+// so the list is never blocked and never reflows.
+const StyledRoot = styled(View)<{
+  rootBottom: number
+  rootPaddingH: number
+}>(({ rootBottom, rootPaddingH }) => ({
+  position: "absolute",
+  left: 0,
+  right: 0,
+  bottom: rootBottom,
+  paddingHorizontal: rootPaddingH,
+  alignItems: "stretch"
+}))
+
+// Positioning context for the card layers. Deliberately left unsized — every
+// layer is absolutely positioned and bottom-anchored, so the stack's own
+// height stays 0 without clipping anything (RN views default to visible
+// overflow).
+const StyledStack = styled(View)({
+  position: "relative",
+  width: "100%"
+})
+
+type StackedCardProps = {
+  item: StackedNotificationItem
+  depth: number
+  revealStep: number
+  onDismiss?: (id: string) => void
+}
+
+/**
+ * One card in the stack. Depth 0 is the front (interactive); 1 and 2 peek
+ * out behind it. Stays mounted across promotions — dismissing the front card
+ * shifts every other card's `depth` down by one — so the position change
+ * springs smoothly instead of jump-cutting. Only truly joining or leaving
+ * the visible stack mounts/unmounts it.
+ */
+const StackedCard = ({
+  item,
+  depth,
+  revealStep,
+  onDismiss
+}: StackedCardProps) => {
+  const depthSV = useSharedValue(depth)
+
+  React.useEffect(() => {
+    depthSV.value = withSpring(depth, SPRING_CONFIG)
+  }, [depth, depthSV])
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateY: depthSV.value * revealStep },
+      { scale: 1 - depthSV.value * SCALE_STEP }
+    ]
+  }))
+
+  const isFront = depth === 0
+
+  return (
+    <Reanimated.View
+      entering={CARD_ENTERING}
+      exiting={CARD_EXITING}
+      pointerEvents={isFront ? "auto" : "none"}
+      accessibilityElementsHidden={!isFront}
+      importantForAccessibility={isFront ? "auto" : "no-hide-descendants"}
+      style={[CARD_BASE_STYLE, { zIndex: -depth }, animatedStyle]}
+    >
+      <Notification
+        variant="toast"
+        type={item.type}
+        onClose={isFront ? () => onDismiss?.(item.id) : undefined}
+      >
+        {item.message}
+      </Notification>
+    </Reanimated.View>
+  )
+}
+
+/**
+ * A last-in-first-out stack of floating notifications pinned to the bottom of
+ * the screen. Only the most recent notification is interactive; up to two
+ * more peek out from behind it (à la iOS notification grouping) so the depth
+ * of the queue is visible, regardless of how many are actually queued.
+ * Dismissing the front one springs the next into place.
+ *
+ * There is no auto-dismiss: a notification persists until its item is removed
+ * from `items` (deselected). Removing then re-adding an item re-raises it to
+ * the top. Fully controlled — the consumer owns the set; this component owns
+ * ordering, dismissal, and enter/exit animation.
+ *
+ * @param {StackedNotificationItem[]} items - Active notifications, ordered by insertion — the last element is the most recent and sits at the front of the stack.
+ * @param {(id: string) => void} [onDismiss] - Called with the item id when its close control is pressed.
+ * @param {number} [bottomOffset] - Distance from the bottom edge in pixels. Defaults to `spacing.lg`.
+ *
+ * @example
+ * ```tsx
+ * import { StackedNotifications } from "@butternutbox/pawprint-native"
+ *
+ * <StackedNotifications
+ *   items={selected.map((a) => ({
+ *     id: a.id,
+ *     type: a.severe ? "warning" : "info",
+ *     message: a.note
+ *   }))}
+ *   onDismiss={(id) => console.log("dismissed", id)}
+ * />
+ * ```
+ */
+export const StackedNotifications = React.forwardRef<
+  View,
+  StackedNotificationsProps
+>(({ items, onDismiss, bottomOffset, ...rest }, ref) => {
+  const theme = useTheme()
+  const { spacing } = theme.tokens.semantics.dimensions
+
+  // Ids the user has closed with the dismiss control. Kept until the item
+  // leaves `items`, so a dismissed-but-still-selected notification stays hidden.
+  const [dismissed, setDismissed] = React.useState<Set<string>>(new Set())
+
+  const idsKey = items.map((item) => item.id).join("|")
+
+  // Prune dismissed ids that are no longer present, so deselect-then-reselect
+  // re-raises the notification. A no-op returns the same Set reference, letting
+  // React bail out of the re-render.
+  React.useEffect(() => {
+    setDismissed((prev) => {
+      if (prev.size === 0) return prev
+      const present = new Set(items.map((item) => item.id))
+      let changed = false
+      const next = new Set<string>()
+      prev.forEach((id) => {
+        if (present.has(id)) next.add(id)
+        else changed = true
+      })
+      return changed ? next : prev
+    })
+  }, [idsKey])
+
+  const activeItems = React.useMemo(
+    () => items.filter((item) => !dismissed.has(item.id)),
+    [items, dismissed]
+  )
+
+  // Front-most first: [front, peek₁, peek₂]. Capped at PEEK_LAYERS behind
+  // the front card regardless of how many are actually queued — the array
+  // index doubles as each card's depth.
+  const layers = React.useMemo(
+    () => activeItems.slice(-(PEEK_LAYERS + 1)).reverse(),
+    [activeItems]
+  )
+
+  const handleDismiss = (id: string) => {
+    setDismissed((prev) => {
+      const next = new Set(prev)
+      next.add(id)
+      return next
+    })
+    onDismiss?.(id)
+  }
+
+  const rootBottom = bottomOffset ?? parseTokenValue(spacing.lg)
+  const peekStep = parseTokenValue(spacing.xs)
+
+  return (
+    <StyledRoot
+      ref={ref}
+      pointerEvents="box-none"
+      rootBottom={rootBottom}
+      rootPaddingH={parseTokenValue(spacing.md)}
+      {...rest}
+    >
+      <StyledStack>
+        {layers.map((item, depth) => (
+          <StackedCard
+            key={item.id}
+            item={item}
+            depth={depth}
+            revealStep={peekStep}
+            onDismiss={handleDismiss}
+          />
+        ))}
+      </StyledStack>
+    </StyledRoot>
+  )
+})
+
+StackedNotifications.displayName = "StackedNotifications"
+
+export type { StackedNotificationItem, StackedNotificationType }

package/src/components/molecules/StackedNotifications/index.ts

@@ -0,0 +1,6 @@
+export { StackedNotifications } from "./StackedNotifications"
+export type {
+  StackedNotificationsProps,
+  StackedNotificationItem,
+  StackedNotificationType
+} from "./StackedNotifications"

package/src/components/molecules/index.ts

@@ -16,6 +16,7 @@ export * from "./SelectField"
 export * from "./NativeSelectPicker"
 export * from "./Slider"
 export * from "./Notification"
+export * from "./StackedNotifications"
 export * from "./Tooltip"
 export * from "./MessageCard"
 export * from "./DatePicker"