@butternutbox/pawprint-native 1.3.1 → 1.5.0

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 }

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

@@ -0,0 +1,87 @@
+import React from "react"
+import { View } from "react-native"
+import { Button, type ButtonProps } from "../../atoms/Button"
+import { IconButton, type IconButtonProps } from "../../atoms/IconButton"
+import {
+  getButtonDefaults,
+  getIconButtonColour,
+  useNavigationHeaderContext
+} from "./NavigationHeaderContext"
+
+export type NavigationHeaderButtonProps = Omit<
+  ButtonProps,
+  "size" | "fullWidth"
+>
+
+export type NavigationHeaderIconButtonProps = Omit<IconButtonProps, "size">
+
+/**
+ * Text button for the navigation header action group. A medium `Button` with
+ * the header defaults: white `filled` / `tertiary` on the `brand` surface and
+ * `outlined` on other surfaces.
+ *
+ * Passing `variant` or `colour` overrides the default.
+ *
+ * @param {"filled" | "outlined" | "text"} [variant] - Button style.
+ * @param {"primary" | "secondary" | "tertiary"} [colour] - Filled colour.
+ *
+ * @example
+ * ```tsx
+ * <NavigationHeader.Button onPress={editQuantity}>
+ *   Pouch quantity
+ * </NavigationHeader.Button>
+ * ```
+ */
+export const NavigationHeaderButton = React.forwardRef<
+  View,
+  NavigationHeaderButtonProps
+>(({ variant, colour, ...props }, ref) => {
+  const defaults = getButtonDefaults(useNavigationHeaderContext())
+
+  return (
+    <Button
+      ref={ref}
+      size="md"
+      variant={variant ?? defaults.variant}
+      colour={colour ?? defaults.colour}
+      {...props}
+    />
+  )
+})
+
+NavigationHeaderButton.displayName = "NavigationHeader.Button"
+
+/**
+ * Icon button for the navigation header action group. A medium filled
+ * `IconButton`, `tertiary` on the `brand` surface and `secondary` on other
+ * surfaces.
+ *
+ * Passing `variant` or `colour` overrides the default.
+ *
+ * @param {PawprintIcon} icon - **(required)** Icon component.
+ * @param {string} aria-label - **(required)** Accessible label.
+ * @param {"filled" | "outlined" | "text"} [variant="filled"] - Button style.
+ * @param {"primary" | "secondary" | "tertiary"} [colour] - Filled colour.
+ *
+ * @example
+ * ```tsx
+ * <NavigationHeader.IconButton icon={Add} aria-label="Add dog" />
+ * ```
+ */
+export const NavigationHeaderIconButton = React.forwardRef<
+  View,
+  NavigationHeaderIconButtonProps
+>(({ colour, ...props }, ref) => {
+  const context = useNavigationHeaderContext()
+
+  return (
+    <IconButton
+      ref={ref}
+      size="md"
+      colour={colour ?? getIconButtonColour(context)}
+      {...props}
+    />
+  )
+})
+
+NavigationHeaderIconButton.displayName = "NavigationHeader.IconButton"

package/src/components/molecules/NavigationHeader/NavigationHeaderContext.ts

@@ -0,0 +1,38 @@
+import React from "react"
+import type { ButtonColour, ButtonVariant } from "../../atoms/Button"
+import type { IconButtonColour } from "../../atoms/IconButton"
+
+type NavigationHeaderSurface = "brand" | "subtle" | "plain"
+
+type NavigationHeaderContextValue = {
+  surface: NavigationHeaderSurface
+}
+
+const NavigationHeaderContext =
+  React.createContext<NavigationHeaderContextValue>({ surface: "brand" })
+
+const useNavigationHeaderContext = () =>
+  React.useContext(NavigationHeaderContext)
+
+const getButtonDefaults = ({
+  surface
+}: NavigationHeaderContextValue): {
+  variant: ButtonVariant
+  colour: ButtonColour
+} =>
+  surface === "brand"
+    ? { variant: "filled", colour: "tertiary" }
+    : { variant: "outlined", colour: "primary" }
+
+const getIconButtonColour = ({
+  surface
+}: NavigationHeaderContextValue): IconButtonColour =>
+  surface === "brand" ? "tertiary" : "secondary"
+
+export {
+  NavigationHeaderContext,
+  useNavigationHeaderContext,
+  getButtonDefaults,
+  getIconButtonColour
+}
+export type { NavigationHeaderSurface, NavigationHeaderContextValue }

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

@@ -0,0 +1,14 @@
+export { NavigationHeader } from "./NavigationHeader"
+export type {
+  NavigationHeaderProps,
+  NavigationHeaderVariant,
+  NavigationHeaderSurface
+} from "./NavigationHeader"
+export {
+  NavigationHeaderButton,
+  NavigationHeaderIconButton
+} from "./NavigationHeaderButton"
+export type {
+  NavigationHeaderButtonProps,
+  NavigationHeaderIconButtonProps
+} from "./NavigationHeaderButton"

package/src/components/molecules/index.ts

@@ -27,3 +27,4 @@ export * from "./ProductListingCard"
 export * from "./ProductDisplayCard"
 export * from "./TabNavigation"
 export * from "./FloatingActionButton"
+export * from "./NavigationHeader"