@butternutbox/pawprint-native 1.3.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@butternutbox/pawprint-native",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "type": "module",
   "description": "ButternutBox Pawprint Design System - React Native Components",
   "main": "./dist/index.cjs",

package/src/components/atoms/Button/Button.stories.tsx

@@ -41,8 +41,8 @@ export default {
     },
     colour: {
       control: { type: "select" },
-      options: ["primary", "secondary"],
-      description: "Colour scheme"
+      options: ["primary", "secondary", "tertiary"],
+      description: "Colour scheme (filled only)"
     },
     loading: {
       control: { type: "boolean" },
@@ -86,7 +86,7 @@ export const AllVariants = () => (
           {variant}
         </Typography>
         <View style={styles.row}>
-          {(["primary", "secondary"] as const).map((colour) => (
+          {(["primary", "secondary", "tertiary"] as const).map((colour) => (
             <Button key={colour} variant={variant} colour={colour}>
               {colour}
             </Button>
@@ -120,7 +120,7 @@ export const AllStates = () => (
   <View style={styles.column}>
     {(["filled", "outlined", "text"] as const).map((variant) => (
       <View key={variant} style={styles.section}>
-        {(["primary", "secondary"] as const).map((colour) => (
+        {(["primary", "secondary", "tertiary"] as const).map((colour) => (
           <View key={colour} style={styles.section}>
             <Typography size="sm" weight="semiBold" color="tertiary">
               {variant} / {colour}

package/src/components/atoms/Button/Button.test.tsx

@@ -2,7 +2,7 @@ import React from "react"
 import { screen } from "@testing-library/react"
 import userEvent from "@testing-library/user-event"
 import { describe, it, expect, vi } from "vitest"
-import { renderWithTheme } from "../../../test-utils"
+import { renderWithTheme, theme } from "../../../test-utils"
 import { Button } from "./Button"
 
 describe("Button", () => {
@@ -36,13 +36,20 @@ describe("Button", () => {
   })
 
   describe("when rendering colours", () => {
-    it.each(["primary", "secondary"] as const)(
+    it.each(["primary", "secondary", "tertiary"] as const)(
       "renders %s colour",
       (colour) => {
         renderWithTheme(<Button colour={colour}>Colour</Button>)
         expect(screen.getByText("Colour")).toBeInTheDocument()
       }
     )
+
+    it("applies the tertiary text colour", () => {
+      renderWithTheme(<Button colour="tertiary">Tertiary</Button>)
+      expect(screen.getByText("Tertiary")).toHaveStyle({
+        color: theme.tokens.semantics.colour.text.action.default
+      })
+    })
   })
 
   describe("when component is interactive", () => {

package/src/components/atoms/Button/Button.tsx

@@ -1,14 +1,14 @@
 import React from "react"
 import { Pressable, View, PressableProps } from "react-native"
 import styled from "@emotion/native"
-import { useTheme } from "@emotion/react"
+import { useTheme, type Theme } from "@emotion/react"
 import { Typography } from "../Typography"
 import { Spinner } from "../Spinner"
 import { resolveFont } from "@butternutbox/pawprint-fonts"
 
 type ButtonVariant = "filled" | "outlined" | "text"
 type ButtonSize = "sm" | "md" | "lg"
-type ButtonColour = "primary" | "secondary"
+type ButtonColour = "primary" | "secondary" | "tertiary"
 
 type ButtonOwnProps = {
   variant?: ButtonVariant
@@ -26,6 +26,35 @@ type ButtonProps = ButtonOwnProps &
 
 const parseTokenValue = (value: string): number => parseFloat(value)
 
+type FilledColourTokens = {
+  background: {
+    default: string
+    selected: string
+    disabled: string
+  }
+  text: { default: string; selected?: string }
+}
+
+const getFilledColourTokens = (
+  theme: Theme,
+  colour: ButtonColour
+): FilledColourTokens => {
+  const buttons = theme.tokens.components.buttons
+
+  if (colour === "tertiary") {
+    const { text } = theme.tokens.semantics.colour
+    return {
+      background: buttons.iconButton.filledButton.colour.background.tertiary,
+      text: { default: text.action.default, selected: text.action.inverse }
+    }
+  }
+
+  return {
+    background: buttons.filledButton.colour.background[colour],
+    text: buttons.filledButton.colour.text[colour]
+  }
+}
+
 const sizeToTypographyKey: Record<ButtonSize, string> = {
   lg: "large",
   md: "medium",
@@ -104,7 +133,7 @@ const StyledSpinnerWrapper = styled(View)({
  *
  * @param variant - *(optional)* Visual variant: filled (default), outlined, or text.
  * @param size - *(optional)* Size variant: sm, md (default), lg
- * @param colour - *(optional)* Colour variant: primary (default), secondary
+ * @param colour - *(optional)* Colour variant: primary (default), secondary, tertiary. Only applies to filled variant.
  * @param loading - *(optional)* Shows spinner and disables interaction
  * @param fullWidth - *(optional)* Stretches button to fill its container
  * @param startIcon - *(optional)* Leading icon element
@@ -150,16 +179,19 @@ const Button = React.forwardRef<View, ButtonProps>(
       spinnerColor: string
     } => {
       if (variant === "filled") {
-        const bgTokens = buttons.filledButton.colour.background[colour]
-        const textToken = buttons.filledButton.colour.text[colour].default
+        const { background: bgTokens, text: textTokens } =
+          getFilledColourTokens(theme, colour)
         return {
           backgroundColor: isDisabled
             ? bgTokens.disabled
             : isPressed
               ? bgTokens.selected
               : bgTokens.default,
-          textColor: textToken,
-          spinnerColor: textToken
+          textColor:
+            isPressed && textTokens.selected
+              ? textTokens.selected
+              : textTokens.default,
+          spinnerColor: textTokens.default
         }
       }
 

package/src/components/molecules/NavigationHeader/NavigationHeader.stories.tsx

@@ -0,0 +1,140 @@
+import React from "react"
+import { View, StyleSheet } from "react-native"
+import { Add, Search, User } from "@butternutbox/pawprint-icons/core"
+import {
+  NavigationHeader,
+  type NavigationHeaderProps,
+  type NavigationHeaderSurface
+} from "./NavigationHeader"
+import { Typography } from "../../atoms/Typography"
+
+const actionElements: Record<string, React.ReactNode> = {
+  None: undefined,
+  Button: <NavigationHeader.Button>Pouch quantity</NavigationHeader.Button>,
+  "Icon buttons + Button": (
+    <>
+      <NavigationHeader.IconButton icon={Search} aria-label="Search" />
+      <NavigationHeader.IconButton icon={Add} aria-label="Add" />
+      <NavigationHeader.Button>Button</NavigationHeader.Button>
+    </>
+  ),
+  "Primary button": (
+    <NavigationHeader.Button variant="filled" colour="primary">
+      Button
+    </NavigationHeader.Button>
+  )
+}
+
+export default {
+  title: "Molecules/NavigationHeader",
+  component: NavigationHeader,
+  argTypes: {
+    title: {
+      control: { type: "text" },
+      description: "Page title, truncated to one line."
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["primary", "secondary"],
+      description:
+        "Header type. `primary` for landing pages; `secondary` adds a back button for child pages."
+    },
+    surface: {
+      control: { type: "select" },
+      options: ["brand", "subtle", "plain"],
+      description: "Background colour."
+    },
+    backLabel: {
+      control: { type: "text" },
+      description: "Accessible label for the back button."
+    },
+    showRadiusPips: {
+      control: { type: "boolean" },
+      description:
+        "Shows the rounded corners below the header. Defaults to `true` on the `brand` surface only."
+    },
+    safeAreaTop: {
+      control: { type: "boolean" },
+      description: "Pads the header by the top safe area inset."
+    },
+    actions: {
+      control: { type: "select" },
+      options: Object.keys(actionElements),
+      mapping: actionElements,
+      description: "Right-hand action group."
+    }
+  }
+}
+
+export const Playground = (args: NavigationHeaderProps) => (
+  <NavigationHeader {...args} />
+)
+Playground.args = {
+  title: "Title",
+  variant: "secondary",
+  surface: "brand",
+  backLabel: "Back",
+  safeAreaTop: false,
+  actions: actionElements["Icon buttons + Button"]
+}
+
+export const AllVariants = () => (
+  <View style={styles.column}>
+    {(["primary", "secondary"] as const).map((variant) => (
+      <NavigationHeader
+        key={variant}
+        variant={variant}
+        title={variant === "primary" ? "Hello, Katie" : "My dog"}
+        safeAreaTop={false}
+        actions={
+          <>
+            <NavigationHeader.IconButton icon={User} aria-label="Account" />
+            <NavigationHeader.Button>Button</NavigationHeader.Button>
+          </>
+        }
+      />
+    ))}
+  </View>
+)
+
+export const AllSurfaces = () => (
+  <View style={styles.column}>
+    {(["brand", "subtle", "plain"] as NavigationHeaderSurface[]).map(
+      (surface) => (
+        <View key={surface} style={styles.section}>
+          <Typography size="sm" weight="semiBold" color="tertiary">
+            {surface}
+          </Typography>
+          <NavigationHeader
+            variant="secondary"
+            surface={surface}
+            title="Recipes"
+            safeAreaTop={false}
+            actions={
+              <>
+                <NavigationHeader.IconButton icon={Add} aria-label="Add" />
+                <NavigationHeader.Button>
+                  Pouch quantity
+                </NavigationHeader.Button>
+              </>
+            }
+          />
+        </View>
+      )
+    )}
+  </View>
+)
+
+export const LongTitle = () => (
+  <NavigationHeader
+    variant="secondary"
+    title="A very long page title that should truncate before the actions"
+    safeAreaTop={false}
+    actions={<NavigationHeader.Button>Pouch quantity</NavigationHeader.Button>}
+  />
+)
+
+const styles = StyleSheet.create({
+  column: { flexDirection: "column", gap: 24 },
+  section: { gap: 8 }
+})

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

@@ -0,0 +1,110 @@
+import React from "react"
+import { screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, it, expect, vi } from "vitest"
+import { renderWithTheme } from "../../../test-utils"
+import { NavigationHeader } from "./NavigationHeader"
+
+const MockIcon = () => <span data-testid="mock-icon" />
+
+describe("NavigationHeader", () => {
+  describe("when component is rendering", () => {
+    it("renders the title", () => {
+      renderWithTheme(<NavigationHeader title="Recipes" />)
+      expect(screen.getByText("Recipes")).toBeInTheDocument()
+    })
+
+    it.each(["primary", "secondary"] as const)(
+      "renders the %s variant",
+      (variant) => {
+        renderWithTheme(<NavigationHeader title="Recipes" variant={variant} />)
+        expect(screen.getByText("Recipes")).toBeInTheDocument()
+      }
+    )
+
+    it.each(["brand", "subtle", "plain"] as const)(
+      "renders the %s surface",
+      (surface) => {
+        renderWithTheme(<NavigationHeader title="Recipes" surface={surface} />)
+        expect(screen.getByText("Recipes")).toBeInTheDocument()
+      }
+    )
+  })
+
+  describe("when rendering the back button", () => {
+    it("does not render it for the primary variant", () => {
+      renderWithTheme(<NavigationHeader title="Home" onBack={vi.fn()} />)
+      expect(screen.queryByLabelText("Back")).not.toBeInTheDocument()
+    })
+
+    it("calls onBack when pressed", async () => {
+      const user = userEvent.setup()
+      const onBack = vi.fn()
+      renderWithTheme(
+        <NavigationHeader title="Recipes" variant="secondary" onBack={onBack} />
+      )
+
+      await user.click(screen.getByLabelText("Back"))
+      expect(onBack).toHaveBeenCalledTimes(1)
+    })
+
+    it("uses a custom back label", () => {
+      renderWithTheme(
+        <NavigationHeader
+          title="Recipes"
+          variant="secondary"
+          backLabel="Retour"
+        />
+      )
+      expect(screen.getByLabelText("Retour")).toBeInTheDocument()
+    })
+  })
+
+  describe("when rendering actions", () => {
+    it("renders text and icon actions", async () => {
+      const user = userEvent.setup()
+      const onPress = vi.fn()
+      renderWithTheme(
+        <NavigationHeader
+          title="Recipes"
+          actions={
+            <>
+              <NavigationHeader.IconButton icon={MockIcon} aria-label="Add" />
+              <NavigationHeader.Button onPress={onPress}>
+                Pouch quantity
+              </NavigationHeader.Button>
+            </>
+          }
+        />
+      )
+      expect(screen.getByLabelText("Add")).toBeInTheDocument()
+
+      await user.click(screen.getByText("Pouch quantity"))
+      expect(onPress).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe("when rendering radius pips", () => {
+    const countPips = (container: HTMLElement) =>
+      container.querySelectorAll('[data-mock="Svg"]').length
+
+    it("renders them on the brand surface by default", () => {
+      const { container } = renderWithTheme(
+        <NavigationHeader title="Recipes" />
+      )
+      expect(countPips(container)).toBe(2)
+    })
+
+    it("hides them on other surfaces unless enabled", () => {
+      const { container, rerender } = renderWithTheme(
+        <NavigationHeader title="Recipes" surface="subtle" />
+      )
+      expect(countPips(container)).toBe(0)
+
+      rerender(
+        <NavigationHeader title="Recipes" surface="subtle" showRadiusPips />
+      )
+      expect(countPips(container)).toBe(2)
+    })
+  })
+})

package/src/components/molecules/NavigationHeader/NavigationHeader.tsx

@@ -0,0 +1,273 @@
+import React from "react"
+import { View, ViewProps } from "react-native"
+import Svg, { Path } from "react-native-svg"
+import { useSafeAreaInsets } from "react-native-safe-area-context"
+import styled from "@emotion/native"
+import { useTheme, type Theme } from "@emotion/react"
+import { ArrowBack } from "@butternutbox/pawprint-icons/core"
+import { IconButton } from "../../atoms/IconButton"
+import { Typography } from "../../atoms/Typography"
+import {
+  NavigationHeaderButton,
+  NavigationHeaderIconButton
+} from "./NavigationHeaderButton"
+import {
+  NavigationHeaderContext,
+  getIconButtonColour,
+  type NavigationHeaderContextValue,
+  type NavigationHeaderSurface
+} from "./NavigationHeaderContext"
+
+type NavigationHeaderVariant = "primary" | "secondary"
+
+type NavigationHeaderOwnProps = {
+  title: string
+  variant?: NavigationHeaderVariant
+  surface?: NavigationHeaderSurface
+  onBack?: () => void
+  backLabel?: string
+  actions?: React.ReactNode
+  showRadiusPips?: boolean
+  safeAreaTop?: boolean
+}
+
+export type NavigationHeaderProps = NavigationHeaderOwnProps &
+  Omit<ViewProps, keyof NavigationHeaderOwnProps | "children">
+
+const parseTokenValue = (value: string): number => parseFloat(value)
+
+const getSurfaceColour = (theme: Theme, surface: NavigationHeaderSurface) => {
+  const { navigationHeader } = theme.tokens.components
+  const { background } = theme.tokens.semantics.colour
+
+  return {
+    brand: navigationHeader.colour.surface.default,
+    subtle: background.surface.secondary,
+    plain: background.surface.default
+  }[surface]
+}
+
+const StyledNavContainer = styled(View)<{
+  containerPaddingTop: number
+  containerPaddingV: number
+  containerPaddingH: number
+  containerGap: number
+  containerBgColor: string
+}>(
+  ({
+    containerPaddingTop,
+    containerPaddingV,
+    containerPaddingH,
+    containerGap,
+    containerBgColor
+  }) => ({
+    flexDirection: "row",
+    alignItems: "center",
+    paddingTop: containerPaddingTop + containerPaddingV,
+    paddingBottom: containerPaddingV,
+    paddingHorizontal: containerPaddingH,
+    gap: containerGap,
+    backgroundColor: containerBgColor
+  })
+)
+
+const StyledTitleGroup = styled(View)<{
+  titleGroupGap: number
+  titleGroupMinHeight: number
+}>(({ titleGroupGap, titleGroupMinHeight }) => ({
+  flex: 1,
+  flexDirection: "row",
+  alignItems: "center",
+  minWidth: 0,
+  minHeight: titleGroupMinHeight,
+  gap: titleGroupGap
+}))
+
+const StyledTitle = styled(View)({
+  flex: 1,
+  minWidth: 0
+})
+
+const StyledActionGroup = styled(View)<{ actionGroupGap: number }>(
+  ({ actionGroupGap }) => ({
+    flexDirection: "row",
+    alignItems: "center",
+    flexShrink: 0,
+    gap: actionGroupGap
+  })
+)
+
+const StyledRadiusPips = styled(View)({
+  flexDirection: "row",
+  justifyContent: "space-between"
+})
+
+const RadiusPips = ({ radius, colour }: { radius: number; colour: string }) => (
+  <StyledRadiusPips
+    accessible={false}
+    importantForAccessibility="no-hide-descendants"
+  >
+    <Svg width={radius} height={radius}>
+      <Path
+        d={`M0 0H${radius}A${radius} ${radius} 0 0 0 0 ${radius}Z`}
+        fill={colour}
+      />
+    </Svg>
+    <Svg width={radius} height={radius}>
+      <Path
+        d={`M${radius} 0H0A${radius} ${radius} 0 0 1 ${radius} ${radius}Z`}
+        fill={colour}
+      />
+    </Svg>
+  </StyledRadiusPips>
+)
+
+/**
+ * Navigation header for the native app. Gives users context of where they
+ * are, a way back, and the most important page-level actions.
+ *
+ * - `primary` — landing pages: large title, no back button.
+ * - `secondary` — child pages: back button and a smaller title.
+ *
+ * Actions are passed via `actions`. Use `NavigationHeader.Button` and
+ * `NavigationHeader.IconButton` for the header defaults, which follow the
+ * surface; their `variant` and `colour` can be overridden. Keep to at most
+ * three.
+ *
+ * Note: Unlike the web version, there is no desktop layout, the header extends
+ * behind the status bar by applying the top safe area inset (`safeAreaTop`),
+ * and `onBack` is a press handler.
+ *
+ * @param {string} title - Page title, truncated to one line.
+ * @param {"primary" | "secondary"} [variant="primary"] - Header type.
+ * @param {"brand" | "subtle" | "plain"} [surface="brand"] - Background colour.
+ *   `brand` is the yellow navigation surface, `subtle` the cream page surface
+ *   and `plain` the default page surface.
+ * @param {() => void} [onBack] - Back button press handler. `secondary` only.
+ * @param {string} [backLabel="Back"] - Accessible label for the back button.
+ *   The back button is `tertiary` on the `brand` surface and `secondary`
+ *   otherwise.
+ * @param {React.ReactNode} [actions] - Right-hand action group.
+ * @param {boolean} [showRadiusPips] - Shows the rounded corners below the
+ *   header. Defaults to `true` on the `brand` surface only.
+ * @param {boolean} [safeAreaTop=true] - Pads the header by the top safe area
+ *   inset.
+ *
+ * @example
+ * ```tsx
+ * import { NavigationHeader } from "@butternutbox/pawprint-native"
+ *
+ * <NavigationHeader
+ *   variant="secondary"
+ *   title="Recipes"
+ *   onBack={navigation.goBack}
+ *   actions={
+ *     <NavigationHeader.Button onPress={editQuantity}>
+ *       Pouch quantity
+ *     </NavigationHeader.Button>
+ *   }
+ * />
+ * ```
+ */
+const NavigationHeaderRoot = React.forwardRef<View, NavigationHeaderProps>(
+  (
+    {
+      title,
+      variant = "primary",
+      surface = "brand",
+      onBack,
+      backLabel = "Back",
+      actions,
+      showRadiusPips = surface === "brand",
+      safeAreaTop = true,
+      ...rest
+    },
+    ref
+  ) => {
+    const theme = useTheme()
+    const { top } = useSafeAreaInsets()
+    const { navigationHeader, buttons } = theme.tokens.components
+    const { spacing } = navigationHeader
+    const surfaceColour = getSurfaceColour(theme, surface)
+    const contextValue = React.useMemo<NavigationHeaderContextValue>(
+      () => ({ surface }),
+      [surface]
+    )
+
+    return (
+      <NavigationHeaderContext.Provider value={contextValue}>
+        <View ref={ref} {...rest}>
+          <StyledNavContainer
+            containerPaddingTop={safeAreaTop ? top : 0}
+            containerPaddingV={parseTokenValue(
+              spacing.navContainer.verticalPadding
+            )}
+            containerPaddingH={parseTokenValue(
+              spacing.navContainer.horizontalPadding
+            )}
+            containerGap={parseTokenValue(spacing.navContainer.gap)}
+            containerBgColor={surfaceColour}
+          >
+            <StyledTitleGroup
+              titleGroupGap={parseTokenValue(spacing.titleGroup.gap)}
+              titleGroupMinHeight={parseTokenValue(buttons.size.md.minHeight)}
+            >
+              {variant === "secondary" && (
+                <IconButton
+                  icon={ArrowBack}
+                  variant="filled"
+                  colour={getIconButtonColour(contextValue)}
+                  size="md"
+                  aria-label={backLabel}
+                  accessibilityRole="button"
+                  onPress={onBack}
+                />
+              )}
+              <StyledTitle>
+                <Typography
+                  token={navigationHeader.typography[variant]}
+                  color={navigationHeader.colour.text.default}
+                  accessibilityRole="header"
+                  noWrap
+                >
+                  {title}
+                </Typography>
+              </StyledTitle>
+            </StyledTitleGroup>
+            {actions && (
+              <StyledActionGroup
+                actionGroupGap={parseTokenValue(spacing.actionGroup.gap)}
+              >
+                {actions}
+              </StyledActionGroup>
+            )}
+          </StyledNavContainer>
+          {showRadiusPips && (
+            <RadiusPips
+              radius={parseTokenValue(
+                theme.tokens.semantics.dimensions.borderRadius.lg
+              )}
+              colour={surfaceColour}
+            />
+          )}
+        </View>
+      </NavigationHeaderContext.Provider>
+    )
+  }
+)
+
+NavigationHeaderRoot.displayName = "NavigationHeader"
+
+type NavigationHeaderComponent = React.ForwardRefExoticComponent<
+  NavigationHeaderProps & React.RefAttributes<View>
+> & {
+  Button: typeof NavigationHeaderButton
+  IconButton: typeof NavigationHeaderIconButton
+}
+
+export const NavigationHeader = Object.assign(NavigationHeaderRoot, {
+  Button: NavigationHeaderButton,
+  IconButton: NavigationHeaderIconButton
+}) as NavigationHeaderComponent
+
+export type { NavigationHeaderVariant, NavigationHeaderSurface }