@btndprojects/loam-ui-native 0.0.0-stage → 0.1.1

package/dist/chunk-YC6WORFL.js

@@ -0,0 +1,535 @@
+import { Coachmark, CoachmarkDots } from './chunk-P23EQNRQ.js';
+import { useTourHost, Highlight, Beacon, useTourInsets } from './chunk-JUAMLEHX.js';
+import { Progress } from './chunk-2ZZ7TDJ4.js';
+import { Button } from './chunk-3ARE4TES.js';
+import { Icon } from './chunk-TKVFVF5D.js';
+import * as React from 'react';
+import { BackHandler, Pressable, View, Text } from 'react-native';
+import { createStyleSheet, useLoamTheme, useStyles } from '@btndprojects/loam-theme-native';
+import { materializeTour, resolveText, stepsForSurface, kindFor, canAttachGate, isStepGated, highlightFor, shouldSkipMissingStep, hintRuns } from '@btndprojects/loam-engage';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+
+var DEFAULT_LABELS = {
+  back: "Back",
+  next: "Next",
+  finish: "Finish",
+  skipStep: "Skip this step",
+  waiting: "Do it to continue",
+  leave: "Leave the tour",
+  minimise: "Minimise \xB7 resume later",
+  resume: "Resume tour",
+  beacon: "Something new here",
+  opening: "Opening",
+  step: "Step"
+};
+var TourContext = React.createContext(null);
+function TourProvider({
+  children,
+  defaultActiveId = null
+}) {
+  const [activeId, setActiveId] = React.useState(defaultActiveId);
+  const listeners = React.useRef(/* @__PURE__ */ new Set());
+  const value = React.useMemo(
+    () => ({
+      activeId,
+      start: setActiveId,
+      stop: () => setActiveId(null),
+      // Copied before iterating: a listener that unsubscribes itself on the
+      // event it was waiting for would otherwise mutate the set mid-loop.
+      track: (event, props) => [...listeners.current].forEach((fn) => fn(event, props)),
+      subscribe: (listener) => {
+        listeners.current.add(listener);
+        return () => listeners.current.delete(listener);
+      }
+    }),
+    [activeId]
+  );
+  return /* @__PURE__ */ jsx(TourContext.Provider, { value, children });
+}
+function useTour() {
+  const ctx = React.useContext(TourContext);
+  if (!ctx) throw new Error("useTour must be used inside a <TourProvider>.");
+  return ctx;
+}
+function Tour({
+  steps,
+  id,
+  name,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  stepIndex: stepProp,
+  defaultStepIndex = 0,
+  onStepIndexChange,
+  variants,
+  variantId,
+  metadata,
+  locale,
+  defaultLocale,
+  surface = "auto",
+  cardVariant,
+  route,
+  onNavigate,
+  onAction,
+  onComplete,
+  onDismiss,
+  onEvent,
+  minimisable = true,
+  labels: labelOverrides,
+  motion = "full"
+}) {
+  const ctx = React.useContext(TourContext);
+  const host = useTourHost();
+  const labels = React.useMemo(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);
+  const touch = surface !== "pointer";
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
+  const open = openProp ?? (id && ctx ? ctx.activeId === id : uncontrolledOpen);
+  const [uncontrolledStep, setUncontrolledStep] = React.useState(defaultStepIndex);
+  const rawIndex = stepProp ?? uncontrolledStep;
+  const [minimised, setMinimised] = React.useState(false);
+  const [beaconOpen, setBeaconOpen] = React.useState(false);
+  const flow = React.useMemo(
+    () => materializeTour(steps, variants, metadata, variantId).steps,
+    [steps, variants, metadata, variantId]
+  );
+  const t = React.useCallback(
+    (value) => resolveText(value, locale, defaultLocale),
+    [locale, defaultLocale]
+  );
+  const visible = React.useMemo(
+    () => stepsForSurface(flow, touch ? "touch" : "pointer"),
+    [flow, touch]
+  );
+  const total = visible.length;
+  const index = Math.min(Math.max(rawIndex, 0), Math.max(0, total - 1));
+  const step = visible[index];
+  const stepRef = React.useRef(step);
+  stepRef.current = step;
+  const emit = React.useCallback(
+    (eventName, props) => {
+      onEvent?.({ name: eventName, step: index, of: total, stepId: step?.id, props });
+    },
+    [onEvent, index, total, step]
+  );
+  const emitRef = React.useRef(emit);
+  emitRef.current = emit;
+  const setIndex = React.useCallback(
+    (next) => {
+      if (stepProp === void 0) setUncontrolledStep(next);
+      onStepIndexChange?.(next);
+    },
+    [stepProp, onStepIndexChange]
+  );
+  const close = React.useCallback(
+    (how) => {
+      if (openProp === void 0) setUncontrolledOpen(false);
+      if (id && ctx && ctx.activeId === id) ctx.stop();
+      onOpenChange?.(false);
+      if (how === "complete") {
+        emitRef.current("tour_completed");
+        onComplete?.();
+      } else {
+        emitRef.current("tour_skipped", { reason: how });
+        onDismiss?.(how);
+      }
+    },
+    [openProp, id, ctx, onOpenChange, onComplete, onDismiss]
+  );
+  const advance = React.useCallback(
+    (via) => {
+      emitRef.current("tour_advanced", { via });
+      if (index >= total - 1) close("complete");
+      else setIndex(index + 1);
+    },
+    [index, total, close, setIndex]
+  );
+  const advanceRef = React.useRef(advance);
+  advanceRef.current = advance;
+  const skipStep = React.useCallback(
+    (reason, props) => {
+      emitRef.current("tour_step_skipped", { reason, ...props });
+      if (index >= total - 1) close("complete");
+      else setIndex(index + 1);
+    },
+    [index, total, close, setIndex]
+  );
+  const skipRef = React.useRef(skipStep);
+  skipRef.current = skipStep;
+  const anchorName = open && !minimised && step?.anchor && step.kind !== "modal" ? step.anchor : null;
+  const [anchorReady, setAnchorReady] = React.useState(false);
+  React.useEffect(() => {
+    setAnchorReady(false);
+    if (!anchorName || !host) return;
+    let alive = true;
+    let timer;
+    const started = Date.now();
+    const look = () => {
+      if (!alive) return;
+      if (host.get(anchorName)?.current) {
+        setAnchorReady(true);
+        return;
+      }
+      if (Date.now() - started >= 2600) {
+        const missing = stepRef.current;
+        if (missing && !shouldSkipMissingStep(missing, kindFor(missing.kind, Boolean(missing.anchor)))) {
+          return;
+        }
+        skipRef.current("anchor-missing", { anchor: anchorName });
+        return;
+      }
+      timer = setTimeout(look, 100);
+    };
+    look();
+    const off = host.subscribe(look);
+    return () => {
+      alive = false;
+      off();
+      if (timer) clearTimeout(timer);
+    };
+  }, [anchorName, host]);
+  const needsRoute = Boolean(open && !minimised && step?.route && route !== void 0 && route !== step.route);
+  const navigatedFor = React.useRef(null);
+  React.useEffect(() => {
+    if (!needsRoute || !onNavigate || !step?.route) return;
+    const key = `${index}:${step.route}`;
+    if (navigatedFor.current === key) return;
+    navigatedFor.current = key;
+    emitRef.current("tour_navigated", { to: step.route });
+    onNavigate(step.route);
+  }, [needsRoute, onNavigate, step, index]);
+  React.useEffect(() => {
+    if (!needsRoute) navigatedFor.current = null;
+  }, [needsRoute, index]);
+  const wasOpen = React.useRef(false);
+  React.useEffect(() => {
+    if (open && !wasOpen.current) emitRef.current("tour_started");
+    wasOpen.current = open;
+  }, [open]);
+  const lastViewed = React.useRef(null);
+  React.useEffect(() => {
+    if (!open || minimised || !step) return;
+    if (anchorName && !anchorReady) return;
+    if (lastViewed.current === String(index)) return;
+    lastViewed.current = String(index);
+    emitRef.current("tour_step_viewed", {
+      anchor: step.anchor ?? null,
+      kind: kindFor(step.kind, Boolean(step.anchor))
+    });
+  }, [open, minimised, step, index, anchorName, anchorReady]);
+  React.useEffect(() => {
+    if (!open) lastViewed.current = null;
+  }, [open]);
+  React.useEffect(() => {
+    setBeaconOpen(false);
+  }, [index]);
+  const advanceOn = step?.advanceOn;
+  const gateAttachable = canAttachGate(advanceOn, Boolean(anchorName && anchorReady), false);
+  const gated = isStepGated(step?.requireAction, advanceOn, gateAttachable);
+  const degradedRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!open || minimised || !advanceOn || advanceOn.type === "next" || gateAttachable) {
+      return;
+    }
+    const key = `${index}:${advanceOn.type}`;
+    if (degradedRef.current === key) return;
+    degradedRef.current = key;
+    emitRef.current("tour_step_skipped", {
+      reason: "gate-unattachable",
+      gate: advanceOn.type,
+      fellBackTo: "next"
+    });
+  }, [open, minimised, advanceOn, gateAttachable, index]);
+  React.useEffect(() => {
+    if (!open || minimised || advanceOn?.type !== "click" || !host || !anchorName) return;
+    return host.subscribePress((pressed) => {
+      if (pressed === anchorName) setTimeout(() => advanceRef.current("click"), 260);
+    });
+  }, [open, minimised, advanceOn, host, anchorName]);
+  React.useEffect(() => {
+    if (!open || minimised || advanceOn?.type !== "event" || !ctx) return;
+    return ctx.subscribe((event) => {
+      if (event === advanceOn.event) advanceRef.current("event");
+    });
+  }, [open, minimised, advanceOn, ctx]);
+  const prevRoute = React.useRef(route);
+  React.useEffect(() => {
+    const before = prevRoute.current;
+    prevRoute.current = route;
+    if (!open || minimised || advanceOn?.type !== "route") return;
+    const want = advanceOn.route ?? step?.route;
+    if (want && route === want && before !== route) advanceRef.current("route");
+  }, [route, open, minimised, advanceOn, step]);
+  React.useEffect(() => {
+    if (!open || minimised) return;
+    const sub = BackHandler.addEventListener("hardwareBackPress", () => {
+      close("back");
+      return true;
+    });
+    return () => sub.remove();
+  }, [open, minimised, close]);
+  if (!open || !step || total === 0) return null;
+  if (minimised) {
+    return /* @__PURE__ */ jsx(
+      TourLauncher,
+      {
+        label: labels.resume,
+        counter: `${index + 1}/${total}`,
+        motion,
+        onPress: () => {
+          setMinimised(false);
+          emitRef.current("tour_resumed");
+        }
+      }
+    );
+  }
+  const kind = kindFor(step.kind, Boolean(step.anchor));
+  const highlight = highlightFor(kind, step.highlight);
+  const resolved = anchorName && anchorReady ? anchorName : null;
+  const waiting = needsRoute || Boolean(step.anchor) && kind !== "modal" && !resolved;
+  const variant = cardVariant ?? (kind === "modal" || !resolved ? "centered" : touch ? "docked" : "anchored");
+  if (kind === "beacon" && resolved && !beaconOpen) {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Highlight, { kind: highlight, target: resolved, padding: step.padding, motion }),
+      /* @__PURE__ */ jsx(
+        Beacon,
+        {
+          target: resolved,
+          accessibilityLabel: t(step.hint) ?? labels.beacon,
+          motion,
+          onPress: () => setBeaconOpen(true)
+        }
+      )
+    ] });
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    resolved ? /* @__PURE__ */ jsx(Highlight, { kind: highlight, target: resolved, padding: step.padding, motion }) : null,
+    /* @__PURE__ */ jsx(
+      TourStepCard,
+      {
+        step,
+        index,
+        total,
+        titles: visible.map((s) => t(s.title) ?? ""),
+        name,
+        target: variant === "anchored" ? resolved : void 0,
+        variant,
+        gated,
+        locale,
+        defaultLocale,
+        waiting: waiting ? `${labels.opening} ${step.route ?? ""}`.trim() : void 0,
+        labels,
+        motion,
+        onNext: () => advance("next"),
+        onBack: index > 0 ? () => setIndex(index - 1) : void 0,
+        onSkipStep: () => skipStep("user-skipped"),
+        onSelectStep: setIndex,
+        onClose: () => close("user"),
+        onMinimise: minimisable ? () => {
+          setMinimised(true);
+          emitRef.current("tour_minimised");
+        } : void 0,
+        onAction: onAction ? (action) => onAction(action, step) : void 0
+      },
+      index
+    )
+  ] });
+}
+function TourHint({ text }) {
+  const { styles } = useStyles(sheet);
+  return /* @__PURE__ */ jsx(Fragment, { children: hintRuns(text).map(
+    (run, i) => run.key ? /* @__PURE__ */ jsx(Text, { style: styles.hintKey, children: run.text }, i) : /* @__PURE__ */ jsx(Text, { children: run.text }, i)
+  ) });
+}
+function TourStepCard({
+  step,
+  index,
+  total,
+  titles,
+  name,
+  target,
+  variant = "docked",
+  gated = false,
+  waiting,
+  labels: labelOverrides,
+  onNext,
+  onBack,
+  onSkipStep,
+  onSelectStep,
+  onClose,
+  onMinimise,
+  onAction,
+  locale,
+  defaultLocale,
+  motion = "full"
+}) {
+  const theme = useLoamTheme();
+  const { styles } = useStyles(sheet);
+  const labels = { ...DEFAULT_LABELS, ...labelOverrides };
+  const t = (value) => resolveText(value, locale, defaultLocale);
+  const isLast = index === total - 1;
+  const kind = kindFor(step.kind, Boolean(step.anchor));
+  const cta = step.cta;
+  return /* @__PURE__ */ jsxs(
+    Coachmark,
+    {
+      target,
+      variant,
+      placement: step.placement ?? "bottom",
+      width: kind === "modal" ? theme.panel.xl : theme.panel.lg,
+      kicker: name,
+      title: t(step.title) ?? "",
+      body: typeof step.body === "string" ? step.body : void 0,
+      media: step.media,
+      hint: waiting ?? (gated ? /* @__PURE__ */ jsx(TourHint, { text: t(step.hint) ?? labels.waiting }) : void 0),
+      motion,
+      onClose,
+      closeLabel: labels.leave,
+      headerActions: onMinimise ? /* @__PURE__ */ jsx(
+        Pressable,
+        {
+          accessibilityRole: "button",
+          accessibilityLabel: labels.minimise,
+          onPress: onMinimise,
+          hitSlop: theme.space[10],
+          style: styles.iconButton,
+          children: /* @__PURE__ */ jsx(Icon, { name: "chevron-down", size: theme.icon.sm, color: theme.color.text3 })
+        }
+      ) : null,
+      actions: /* @__PURE__ */ jsxs(Fragment, { children: [
+        onBack ? /* @__PURE__ */ jsx(Button, { size: "sm", variant: "outline", onPress: onBack, children: labels.back }) : null,
+        gated ? step.skippable === false ? null : /* @__PURE__ */ jsx(Button, { size: "sm", variant: "ghost", onPress: onSkipStep, children: labels.skipStep }) : /* @__PURE__ */ jsx(Button, { size: "lg", variant: "primary", onPress: onNext, children: isLast ? labels.finish : labels.next })
+      ] }),
+      children: [
+        typeof step.body !== "string" && step.body ? /* @__PURE__ */ jsx(Fragment, { children: step.body }) : null,
+        cta ? /* @__PURE__ */ jsx(Button, { size: "sm", variant: "ghost", trailingIcon: "arrow-right", onPress: () => onAction?.(cta.action), children: cta.label }) : null,
+        /* @__PURE__ */ jsx(
+          TourProgress,
+          {
+            index,
+            total,
+            titles,
+            stepLabel: labels.step,
+            onSelect: onSelectStep
+          }
+        )
+      ]
+    }
+  );
+}
+function TourProgress({
+  index,
+  total,
+  titles,
+  onSelect,
+  stepLabel = "Step"
+}) {
+  const { styles } = useStyles(sheet);
+  return /* @__PURE__ */ jsxs(View, { style: styles.progress, children: [
+    /* @__PURE__ */ jsx(
+      Progress,
+      {
+        size: "sm",
+        value: index + 1,
+        max: Math.max(1, total),
+        accessibilityLabel: `${stepLabel} ${index + 1} of ${total}`
+      }
+    ),
+    /* @__PURE__ */ jsxs(View, { style: styles.progressRail, children: [
+      /* @__PURE__ */ jsx(
+        CoachmarkDots,
+        {
+          total,
+          index,
+          onSelect,
+          stepLabel,
+          titles
+        }
+      ),
+      /* @__PURE__ */ jsxs(Text, { style: styles.counter, children: [
+        index + 1,
+        " / ",
+        total
+      ] })
+    ] })
+  ] });
+}
+function TourLauncher({
+  label = "Resume tour",
+  counter,
+  onPress,
+  pinned = true
+}) {
+  const theme = useLoamTheme();
+  const { styles } = useStyles(sheet);
+  const insets = useTourInsets();
+  return /* @__PURE__ */ jsxs(
+    Pressable,
+    {
+      accessibilityRole: "button",
+      accessibilityLabel: counter ? `${label} \u2014 ${counter}` : label,
+      onPress,
+      style: ({ pressed }) => [
+        styles.launcher,
+        pinned ? styles.launcherPinned : null,
+        pinned ? { right: theme.space[16] + insets.right, bottom: theme.space[16] + insets.bottom } : null,
+        pressed ? { backgroundColor: theme.state.pressed } : null
+      ],
+      children: [
+        /* @__PURE__ */ jsx(Icon, { name: "star", size: theme.icon.sm, color: theme.color.accentStrong }),
+        /* @__PURE__ */ jsx(Text, { style: styles.launcherLabel, children: label }),
+        counter ? /* @__PURE__ */ jsx(Text, { style: styles.counter, children: counter }) : null
+      ]
+    }
+  );
+}
+var sheet = createStyleSheet((theme) => ({
+  /** A control named inside a gated hint, shaped like the app's own label. */
+  hintKey: {
+    fontFamily: theme.font.sans,
+    color: theme.color.text,
+    textTransform: "none"
+  },
+  iconButton: {
+    width: theme.ctl.sm,
+    height: theme.ctl.sm,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radius.full
+  },
+  progress: { gap: theme.space[8], marginTop: theme.space[2] },
+  progressRail: { flexDirection: "row", alignItems: "center", gap: theme.space[6] },
+  counter: {
+    marginLeft: "auto",
+    fontFamily: theme.font.mono,
+    fontSize: theme.type.caption2.fontSize,
+    color: theme.color.text3,
+    fontVariant: ["tabular-nums"]
+  },
+  launcher: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.space[9],
+    height: theme.ctl.lg,
+    paddingHorizontal: theme.space[15],
+    borderRadius: theme.radius.full,
+    borderWidth: theme.borderWidth.thin,
+    // The pill's edge is the only thing separating it from the screen behind,
+    // so it is a graphical edge at 3:1 — the measured accent, not the raw one.
+    borderColor: theme.focus.ringColor,
+    backgroundColor: theme.color.surface,
+    ...theme.shadow.lg
+  },
+  launcherPinned: {
+    position: "absolute",
+    right: theme.space[16],
+    bottom: theme.space[16]
+  },
+  launcherLabel: {
+    fontFamily: theme.font.sans,
+    fontWeight: theme.fontWeight.bold,
+    fontSize: theme.type.subheadline.fontSize,
+    color: theme.color.accentStrong
+  }
+}));
+
+export { Tour, TourLauncher, TourProgress, TourProvider, TourStepCard, useTour };

package/dist/chunk-YDGVJETP.js

@@ -0,0 +1,60 @@
+import { ErrorSummary } from './chunk-C2NTXVWM.js';
+import * as React from 'react';
+import { View } from 'react-native';
+import { createStyleSheet, useStyles } from '@btndprojects/loam-theme-native';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+var FormContext = React.createContext(null);
+function useFormContext() {
+  const ctx = React.useContext(FormContext);
+  if (!ctx) throw new Error("useFormContext must be used inside a <Form>");
+  return ctx;
+}
+function Form({
+  onSubmit,
+  onValidate,
+  onFocusField,
+  submitting = false,
+  motion = "full",
+  children
+}) {
+  const { styles } = useStyles(sheet);
+  const [errors, setErrors] = React.useState([]);
+  const submit = React.useCallback(async () => {
+    if (submitting) return;
+    if (onValidate) {
+      const found = await onValidate();
+      if (found.length > 0) {
+        setErrors(found);
+        const first = found[0];
+        if (first) onFocusField?.(first.fieldId);
+        return;
+      }
+    }
+    setErrors([]);
+    await onSubmit();
+  }, [submitting, onValidate, onFocusField, onSubmit]);
+  const ctx = React.useMemo(() => ({ submit, submitting }), [submit, submitting]);
+  return /* @__PURE__ */ jsx(FormContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxs(View, { style: styles.form, children: [
+    /* @__PURE__ */ jsx(ErrorSummary, { errors, motion, onFocusField }),
+    children
+  ] }) });
+}
+function FormActions({ children }) {
+  const { styles } = useStyles(sheet);
+  return /* @__PURE__ */ jsx(View, { style: styles.actions, children });
+}
+var sheet = createStyleSheet((theme) => ({
+  form: {
+    gap: theme.space.s5
+  },
+  actions: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: theme.space.s3,
+    paddingTop: theme.space.s1
+  }
+}));
+
+export { Form, FormActions, useFormContext };