@butternutbox/pawprint-native 0.0.1 → 0.1.0

package/src/components/molecules/PictureSelector/PictureSelector.tsx

@@ -0,0 +1,313 @@
+import React from "react"
+import { View, Pressable, ViewProps, PressableProps } from "react-native"
+import styled from "@emotion/native"
+import { useTheme } from "@emotion/react"
+import { Icon, type PawprintIcon } from "../../atoms/Icon"
+import { Illustration } from "../../atoms/Illustration"
+import { Typography } from "../../atoms/Typography"
+import { MessageCard } from "../MessageCard"
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type PawprintIllustration = React.ComponentType<{
+  width?: number
+  height?: number
+}>
+
+export type PictureSelectorItem = {
+  value: string
+  illustration?: PawprintIllustration
+  icon?: PawprintIcon
+  disabled?: boolean
+  ariaLabel?: string
+  insightTitle?: string
+  insightDescription?: React.ReactNode
+}
+
+type PictureSelectorOwnProps = {
+  label?: string
+  items: PictureSelectorItem[]
+  value?: string
+  defaultValue?: string
+  onValueChange?: (value: string) => void
+  /** Optional fixed card width (px). Defaults to `100%` (fluid). */
+  itemWidth?: number
+  /** Card aspect ratio (width / height). Defaults to `1` (square). */
+  itemAspectRatio?: number
+  /** Optional floor on each card's width (px). No default. */
+  itemMinWidth?: number
+  /** Optional floor on each card's height (px). No default. */
+  itemMinHeight?: number
+}
+
+export type PictureSelectorProps = PictureSelectorOwnProps &
+  Omit<ViewProps, keyof PictureSelectorOwnProps>
+
+type PressableOwnForItem = Omit<PressableProps, "onPress" | "disabled">
+
+// ─── Pointer shape ────────────────────────────────────────────────────────────
+
+// TODO: add to pictureSelector.json — pointer is 24w × 12h triangle in Figma.
+// These aren't container dimensions — they're the triangle's border widths
+// (the CSS/RN triangle trick), which *are* the shape itself.
+const POINTER_HALF_WIDTH = 12
+const POINTER_HEIGHT = 12
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const parseTokenValue = (value: string): number => parseFloat(value)
+
+// ─── Styled primitives ────────────────────────────────────────────────────────
+
+const StyledRoot = styled(View)<{ rootGap: number }>(({ rootGap }) => ({
+  flexDirection: "column",
+  gap: rootGap,
+  width: "100%"
+}))
+
+const StyledRow = styled(View)<{ rowGap: number }>(({ rowGap }) => ({
+  flexDirection: "row",
+  alignItems: "flex-start",
+  gap: rowGap,
+  width: "100%"
+}))
+
+const StyledItemStack = styled(View)<{ stackGap: number }>(({ stackGap }) => ({
+  flexDirection: "column",
+  alignItems: "center",
+  gap: stackGap,
+  flex: 1,
+  minWidth: 0
+}))
+
+const StyledPictureButton = styled(Pressable)<{
+  buttonBorderRadius: number
+  buttonBorderWidth: number
+  buttonBorderColor: string
+  buttonBgColor: string
+  buttonPadding: number
+  buttonOpacity: number
+  buttonWidth?: number
+  buttonAspectRatio: number
+  buttonMinWidth?: number
+  buttonMinHeight?: number
+}>(
+  ({
+    buttonBorderRadius,
+    buttonBorderWidth,
+    buttonBorderColor,
+    buttonBgColor,
+    buttonPadding,
+    buttonOpacity,
+    buttonWidth,
+    buttonAspectRatio,
+    buttonMinWidth,
+    buttonMinHeight
+  }) => ({
+    alignItems: "center",
+    justifyContent: "center",
+    width: buttonWidth !== undefined ? buttonWidth : "100%",
+    aspectRatio: buttonAspectRatio,
+    ...(buttonMinWidth !== undefined && { minWidth: buttonMinWidth }),
+    ...(buttonMinHeight !== undefined && { minHeight: buttonMinHeight }),
+    padding: buttonPadding,
+    borderRadius: buttonBorderRadius,
+    borderWidth: buttonBorderWidth,
+    borderColor: buttonBorderColor,
+    backgroundColor: buttonBgColor,
+    opacity: buttonOpacity,
+    overflow: "hidden"
+  })
+)
+
+const StyledPointerTriangle = styled(View)<{
+  pointerColor: string
+  pointerVisible: boolean
+}>(({ pointerColor, pointerVisible }) => ({
+  // 0×0 is part of the RN triangle-via-borders trick, not a layout
+  // dimension. Borders compose into a down-pointing triangle (apex at
+  // bottom) on RN; the `rotate 180deg` transform flips it to apex-up so
+  // the pointer visually connects the selected button to the insight
+  // card below. Using rotate instead of `borderBottom` because RN's
+  // triangle-via-borders rendering is inconsistent when the coloured
+  // border is on the bottom with transparent left/right on certain
+  // platforms.
+  width: 0,
+  height: 0,
+  borderLeftWidth: POINTER_HALF_WIDTH,
+  borderRightWidth: POINTER_HALF_WIDTH,
+  borderTopWidth: POINTER_HEIGHT,
+  borderLeftColor: "transparent",
+  borderRightColor: "transparent",
+  borderTopColor: pointerColor,
+  borderStyle: "solid",
+  transform: [{ rotate: "180deg" }],
+  opacity: pointerVisible ? 1 : 0
+}))
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+/**
+ * A horizontal group of image/illustration buttons where one is selectable at
+ * a time. When the selected item has `insightTitle`/`insightDescription`, a
+ * `MessageCard.Insight` (standalone variant) renders below the row with a
+ * pointer beneath the selected button linking the two. The pointer moves with
+ * the selection.
+ *
+ * By default each card fills the width of its flex item (`width: 100%`)
+ * and is square (`aspectRatio: 1`). Override with `itemWidth` for a fixed
+ * width, `itemAspectRatio` for a non-square shape, and `itemMinWidth` /
+ * `itemMinHeight` for per-dim minimum floors.
+ *
+ * @param {string} [label] - Optional headline above the row.
+ * @param {PictureSelectorItem[]} items - 3 or 4 items to choose between.
+ * @param {string} [value] - Controlled selected value.
+ * @param {string} [defaultValue] - Uncontrolled initial selected value.
+ * @param {(value: string) => void} [onValueChange] - Fires when selection changes.
+ * @param {number} [itemWidth] - Fixed card width (px). Defaults to `100%`.
+ * @param {number} [itemAspectRatio=1] - Card aspect ratio (width / height).
+ * @param {number} [itemMinWidth] - Optional override for the card's min-width.
+ *   Defaults to `pictureButton.size.minWidth` (80px).
+ * @param {number} [itemMinHeight] - Optional override for the card's min-height.
+ *   Defaults to `pictureButton.size.minHeight` (120px).
+ */
+export const PictureSelector = React.forwardRef<View, PictureSelectorProps>(
+  (
+    {
+      label,
+      items,
+      value,
+      defaultValue,
+      onValueChange,
+      itemWidth,
+      itemAspectRatio = 1,
+      itemMinWidth,
+      itemMinHeight,
+      ...rest
+    },
+    ref
+  ) => {
+    const theme = useTheme()
+    const { pictureSelector } = theme.tokens.components
+    const { pictureButton } = pictureSelector
+
+    const isControlled = value !== undefined
+    const [internalValue, setInternalValue] = React.useState<
+      string | undefined
+    >(defaultValue)
+    const selectedValue = isControlled ? value : internalValue
+    const selectedItem = items.find((item) => item.value === selectedValue)
+    const hasInsight = Boolean(
+      selectedItem?.insightTitle || selectedItem?.insightDescription
+    )
+
+    const handleSelect = (nextValue: string) => {
+      if (!isControlled) setInternalValue(nextValue)
+      onValueChange?.(nextValue)
+    }
+
+    const rootGap = parseTokenValue(pictureSelector.spacing.container.gap)
+    const rowGap = parseTokenValue(pictureSelector.spacing.buttons.gap)
+    const stackGap = parseTokenValue(pictureButton.spacing.container.gap)
+    const buttonPadding = parseTokenValue(pictureButton.spacing.padding)
+    const buttonBorderRadius = parseTokenValue(
+      pictureButton.borderRadius.default
+    )
+    const borderWidthDefault = parseTokenValue(
+      pictureButton.borderWidth.default
+    )
+    const borderWidthActive = parseTokenValue(pictureButton.borderWidth.active)
+    const resolvedMinWidth =
+      itemMinWidth ?? parseTokenValue(pictureButton.size.minWidth)
+    // Default min-height to min-width so the cards stay square at the floor,
+    // regardless of how many items are in the row.
+    const resolvedMinHeight = itemMinHeight ?? resolvedMinWidth
+
+    return (
+      <StyledRoot
+        ref={ref}
+        rootGap={rootGap}
+        accessible
+        accessibilityRole="radiogroup"
+        accessibilityLabel={label}
+        {...rest}
+      >
+        {label && (
+          <Typography
+            token={pictureSelector.typography.label}
+            color={pictureSelector.colour.text.default}
+          >
+            {label}
+          </Typography>
+        )}
+        <StyledRow rowGap={rowGap}>
+          {items.map((item) => {
+            const isSelected = item.value === selectedValue
+            const Visual = item.illustration
+            const IconComp = item.icon
+            const buttonProps: Omit<
+              React.ComponentProps<typeof StyledPictureButton>,
+              keyof PressableOwnForItem
+            > = {
+              buttonBorderRadius,
+              buttonBorderWidth: isSelected
+                ? borderWidthActive
+                : borderWidthDefault,
+              buttonBorderColor: isSelected
+                ? pictureButton.colour.border.active
+                : pictureButton.colour.border.default,
+              buttonBgColor: isSelected
+                ? pictureButton.colour.background.active
+                : pictureButton.colour.background.default,
+              buttonPadding,
+              buttonOpacity: item.disabled ? 0.5 : 1,
+              buttonWidth: itemWidth,
+              buttonAspectRatio: itemAspectRatio,
+              buttonMinWidth: resolvedMinWidth,
+              buttonMinHeight: resolvedMinHeight
+            }
+
+            return (
+              <StyledItemStack key={item.value} stackGap={stackGap}>
+                <StyledPictureButton
+                  accessible
+                  accessibilityRole="radio"
+                  accessibilityState={{
+                    selected: isSelected,
+                    disabled: item.disabled
+                  }}
+                  accessibilityLabel={item.ariaLabel}
+                  disabled={item.disabled}
+                  onPress={() => {
+                    if (!item.disabled) handleSelect(item.value)
+                  }}
+                  {...buttonProps}
+                >
+                  {Visual ? (
+                    <Illustration illustration={Visual} size="sm" />
+                  ) : IconComp ? (
+                    <Icon icon={IconComp} size="2xl" />
+                  ) : null}
+                </StyledPictureButton>
+                <StyledPointerTriangle
+                  pointerColor={pictureButton.colour.pointer.default}
+                  pointerVisible={isSelected && hasInsight}
+                />
+              </StyledItemStack>
+            )
+          })}
+        </StyledRow>
+        {hasInsight && selectedItem && (
+          <MessageCard.Insight
+            variant="standalone"
+            title={selectedItem.insightTitle}
+          >
+            {selectedItem.insightDescription}
+          </MessageCard.Insight>
+        )}
+      </StyledRoot>
+    )
+  }
+)
+
+PictureSelector.displayName = "PictureSelector"

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

@@ -0,0 +1,5 @@
+export { PictureSelector } from "./PictureSelector"
+export type {
+  PictureSelectorProps,
+  PictureSelectorItem
+} from "./PictureSelector"

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

@@ -0,0 +1,145 @@
+import React from "react"
+import { View, StyleSheet } from "react-native"
+import { Progress } from "./Progress"
+import type { ProgressProps } from "./Progress"
+import { Typography } from "../../atoms/Typography"
+
+export default {
+  title: "Molecules/Progress",
+  component: Progress,
+  argTypes: {
+    value: {
+      control: { type: "range", min: 0, max: 100, step: 1 },
+      description: "Current progress value (0 to max)"
+    },
+    max: {
+      control: { type: "number" },
+      description: "Maximum value representing 100% completion"
+    },
+    size: {
+      control: { type: "select" },
+      options: ["sm", "lg"],
+      description: "Track height (sm: 8px, lg: 16px)"
+    },
+    colour: {
+      control: { type: "select" },
+      options: ["primary", "secondary"],
+      description: "Indicator fill colour"
+    },
+    label: {
+      control: { type: "text" },
+      description: "Label rendered above the track (left)"
+    },
+    description: {
+      control: { type: "text" },
+      description: "Helper text rendered above the track (right)"
+    }
+  }
+}
+
+export const Playground = {
+  args: {
+    value: 50,
+    max: 100,
+    size: "sm",
+    colour: "primary",
+    label: "Label",
+    description: "Help text"
+  },
+  render: (args: ProgressProps) => (
+    <View style={styles.container}>
+      <Progress {...args} />
+    </View>
+  )
+}
+
+export const Small = {
+  name: "Small",
+  render: () => (
+    <View style={styles.column}>
+      <Progress size="sm" value={0} label="Label" description="0%" />
+      <Progress size="sm" value={30} label="Label" description="30%" />
+      <Progress size="sm" value={60} label="Label" description="60%" />
+      <Progress size="sm" value={100} label="Label" description="100%" />
+    </View>
+  )
+}
+
+export const Large = {
+  name: "Large",
+  render: () => (
+    <View style={styles.column}>
+      <Progress size="lg" value={0} label="Label" description="0%" />
+      <Progress size="lg" value={30} label="Label" description="30%" />
+      <Progress size="lg" value={60} label="Label" description="60%" />
+      <Progress size="lg" value={100} label="Label" description="100%" />
+    </View>
+  )
+}
+
+export const Colours = {
+  name: "Colours",
+  render: () => (
+    <View style={styles.column}>
+      <View style={styles.section}>
+        <Typography size="sm" weight="semiBold" color="tertiary">
+          Primary (Yellow)
+        </Typography>
+        <Progress value={60} colour="primary" />
+      </View>
+      <View style={styles.section}>
+        <Typography size="sm" weight="semiBold" color="tertiary">
+          Secondary (Brown)
+        </Typography>
+        <Progress value={60} colour="secondary" />
+      </View>
+    </View>
+  )
+}
+
+export const WithoutHeader = {
+  name: "Without Header",
+  render: () => (
+    <View style={styles.column}>
+      <Progress size="sm" value={40} />
+      <Progress size="lg" value={70} />
+    </View>
+  )
+}
+
+export const FractionalValue = {
+  name: "Fractional Value",
+  render: () => (
+    <View style={styles.column}>
+      <Progress
+        size="lg"
+        value={14}
+        max={14}
+        label="Box capacity"
+        description="14/14"
+      />
+      <Progress
+        size="lg"
+        value={9}
+        max={14}
+        label="Box capacity"
+        description="9/14"
+      />
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 16
+  },
+  column: {
+    padding: 16,
+    flexDirection: "column",
+    gap: 16
+  },
+  section: {
+    flexDirection: "column",
+    gap: 8
+  }
+})

package/src/components/molecules/Progress/Progress.tsx

@@ -0,0 +1,184 @@
+import React from "react"
+import { View, ViewProps } from "react-native"
+import styled from "@emotion/native"
+import { useTheme } from "@emotion/react"
+import * as ProgressPrimitive from "@rn-primitives/progress"
+import { Typography } from "../../atoms/Typography"
+
+type ProgressSize = "sm" | "lg"
+type ProgressColour = "primary" | "secondary"
+
+type ProgressOwnProps = {
+  value?: number
+  max?: number
+  size?: ProgressSize
+  colour?: ProgressColour
+  label?: React.ReactNode
+  description?: React.ReactNode
+  getValueLabel?: (value: number, max: number) => string
+}
+
+export type ProgressProps = ProgressOwnProps &
+  Omit<ViewProps, keyof ProgressOwnProps>
+
+const parseTokenValue = (value: string): number => parseFloat(value)
+
+const StyledRoot = styled(View)<{ rootGap: number }>(({ rootGap }) => ({
+  flexDirection: "column",
+  alignItems: "stretch",
+  gap: rootGap,
+  width: "100%"
+}))
+
+const StyledHeader = styled(View)({
+  flexDirection: "row",
+  alignItems: "center",
+  justifyContent: "space-between",
+  width: "100%"
+})
+
+const StyledTrack = styled(View)<{
+  trackHeight: number
+  trackMinWidth: number
+  trackBorderRadius: number
+  trackBgColor: string
+}>(({ trackHeight, trackMinWidth, trackBorderRadius, trackBgColor }) => ({
+  position: "relative",
+  width: "100%",
+  minWidth: trackMinWidth,
+  height: trackHeight,
+  borderRadius: trackBorderRadius,
+  backgroundColor: trackBgColor,
+  overflow: "hidden"
+}))
+
+const StyledIndicator = styled(View)<{
+  indicatorBorderRadius: number
+  indicatorBgColor: string
+}>(({ indicatorBorderRadius, indicatorBgColor }) => ({
+  height: "100%",
+  borderRadius: indicatorBorderRadius,
+  backgroundColor: indicatorBgColor
+}))
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.max(min, Math.min(max, value))
+
+/**
+ * A horizontal progress bar that visualises the completion of a determinate
+ * task. Supports an optional label (top-left) and description (top-right),
+ * two sizes, and two indicator colours.
+ *
+ * Wraps `@rn-primitives/progress` for accessibility.
+ *
+ * @param {number} [value=0] - Current progress value (0 to `max`). Clamped.
+ * @param {number} [max=100] - Maximum value representing 100% completion.
+ * @param {"sm" | "lg"} [size="sm"] - Track height: sm (8px) or lg (16px).
+ * @param {"primary" | "secondary"} [colour="primary"] - Indicator fill colour.
+ * @param {React.ReactNode} [label] - Label rendered in the top-left above the track.
+ * @param {React.ReactNode} [description] - Helper text rendered in the top-right above the track.
+ * @param {(value: number, max: number) => string} [getValueLabel] - Accessible value label.
+ *
+ * @example
+ * ```tsx
+ * import { Progress } from "@butternutbox/pawprint-native"
+ *
+ * <Progress label="Box capacity" description="14/14" value={100} />
+ * ```
+ */
+export const Progress = React.forwardRef<View, ProgressProps>(
+  (
+    {
+      value = 0,
+      max = 100,
+      size = "sm",
+      colour = "primary",
+      label,
+      description,
+      getValueLabel,
+      ...rest
+    },
+    ref
+  ) => {
+    const theme = useTheme()
+    const {
+      track,
+      indicator,
+      borderRadius,
+      spacing,
+      typography,
+      colour: textColour
+    } = theme.tokens.components.progress
+
+    const safeMax = max > 0 ? max : 100
+    const clampedValue = clamp(value, 0, safeMax)
+    const percent = (clampedValue / safeMax) * 100
+    const showHeader = Boolean(label) || Boolean(description)
+    const typographyForSize =
+      size === "lg" ? typography.large : typography.small
+
+    const trackSize = { lg: track.size.large, sm: track.size.small }[size]
+    const trackHeight = parseTokenValue(trackSize.height)
+    const trackMinWidth = parseTokenValue(trackSize.mindWidth)
+    const trackBorderRadius = parseTokenValue(borderRadius.track.default)
+    const indicatorBorderRadius = parseTokenValue(
+      borderRadius.indicator.default
+    )
+    const indicatorBgColor =
+      colour === "secondary"
+        ? indicator.colour.background.secondary
+        : indicator.colour.background.primary
+
+    return (
+      <StyledRoot ref={ref} rootGap={parseTokenValue(spacing.gap)} {...rest}>
+        {showHeader && (
+          <StyledHeader>
+            {label ? (
+              <Typography
+                token={typographyForSize.label}
+                color={textColour.text.label}
+              >
+                {label}
+              </Typography>
+            ) : (
+              <View />
+            )}
+            {description ? (
+              <Typography
+                token={typographyForSize.description}
+                color={textColour.text.helper}
+              >
+                {description}
+              </Typography>
+            ) : (
+              <View />
+            )}
+          </StyledHeader>
+        )}
+        <ProgressPrimitive.Root
+          value={clampedValue}
+          max={safeMax}
+          getValueLabel={getValueLabel}
+          asChild
+        >
+          <StyledTrack
+            trackHeight={trackHeight}
+            trackMinWidth={trackMinWidth}
+            trackBorderRadius={trackBorderRadius}
+            trackBgColor={track.colour.background.default}
+          >
+            <ProgressPrimitive.Indicator asChild>
+              <StyledIndicator
+                indicatorBorderRadius={indicatorBorderRadius}
+                indicatorBgColor={indicatorBgColor}
+                style={{ width: `${percent}%` }}
+              />
+            </ProgressPrimitive.Indicator>
+          </StyledTrack>
+        </ProgressPrimitive.Root>
+      </StyledRoot>
+    )
+  }
+)
+
+Progress.displayName = "Progress"

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

@@ -0,0 +1,2 @@
+export { Progress } from "./Progress"
+export type { ProgressProps } from "./Progress"