@studio-piot/native-ui 0.1.0

package/src/components/Field/resolveFieldBorder.test.ts

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  resolveFieldBorder,
+  shouldShowFieldClear,
+} from "./resolveFieldBorder.ts";
+
+const colors = {
+  borderColor: "#aaa",
+  focusedBorderColor: "#00f",
+  errorColor: "#f00",
+};
+
+describe("resolveFieldBorder", () => {
+  it("resting: width 1 and borderColor", () => {
+    const next = resolveFieldBorder({
+      isFocused: false,
+      hasError: false,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 1);
+    assert.equal(next.borderColor, "#aaa");
+    assert.equal(next.paddingHorizontal, 14);
+  });
+
+  it("focused without error: width 2, focused colour, padding -1", () => {
+    const next = resolveFieldBorder({
+      isFocused: true,
+      hasError: false,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 2);
+    assert.equal(next.borderColor, "#00f");
+    assert.equal(next.paddingHorizontal, 13);
+  });
+
+  it("error without focus: width 1, error colour", () => {
+    const next = resolveFieldBorder({
+      isFocused: false,
+      hasError: true,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 1);
+    assert.equal(next.borderColor, "#f00");
+    assert.equal(next.paddingHorizontal, 14);
+  });
+
+  it("focused + error: width 2, error colour wins", () => {
+    const next = resolveFieldBorder({
+      isFocused: true,
+      hasError: true,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 2);
+    assert.equal(next.borderColor, "#f00");
+    assert.equal(next.paddingHorizontal, 13);
+  });
+});
+
+describe("shouldShowFieldClear", () => {
+  it("false when value empty", () => {
+    assert.equal(shouldShowFieldClear("", true), false);
+  });
+
+  it("false when no clear icon", () => {
+    assert.equal(shouldShowFieldClear("hi", false), false);
+  });
+
+  it("true when value and clear icon", () => {
+    assert.equal(shouldShowFieldClear("hi", true), true);
+  });
+
+  it("false when not editable", () => {
+    assert.equal(shouldShowFieldClear("hi", true, false), false);
+  });
+});

package/src/components/Field/resolveFieldBorder.ts

@@ -0,0 +1,40 @@
+const RESTING_PADDING_HORIZONTAL = 14;
+
+export type ResolveFieldBorderInput = {
+  isFocused: boolean;
+  hasError: boolean;
+  borderColor: string;
+  focusedBorderColor: string;
+  errorColor: string;
+  restingPaddingHorizontal?: number;
+};
+
+export type ResolveFieldBorderResult = {
+  borderColor: string;
+  borderWidth: number;
+  paddingHorizontal: number;
+};
+
+export function resolveFieldBorder(
+  input: ResolveFieldBorderInput,
+): ResolveFieldBorderResult {
+  const resting =
+    input.restingPaddingHorizontal ?? RESTING_PADDING_HORIZONTAL;
+  const borderWidth = input.isFocused ? 2 : 1;
+  const borderColor = input.hasError
+    ? input.errorColor
+    : input.isFocused
+      ? input.focusedBorderColor
+      : input.borderColor;
+  const paddingHorizontal = input.isFocused ? resting - 1 : resting;
+
+  return { borderColor, borderWidth, paddingHorizontal };
+}
+
+export function shouldShowFieldClear(
+  value: string,
+  hasClearIcon: boolean,
+  editable = true,
+): boolean {
+  return value.length > 0 && hasClearIcon && editable;
+}

package/src/components/Field/resolveFieldColor.test.ts

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FIELD_THEME_ROLES } from "./fieldThemeRoles.ts";
+import { resolveFieldColor } from "./resolveFieldColor.ts";
+
+const ctx = {
+  colors: {
+    light: {
+      fieldBorder: "#aaa",
+      fieldFocusedBorder: "#00f",
+      fieldError: "#f00",
+      fieldText: "#111",
+      fieldLabel: "#666",
+      fieldPlaceholder: "#666",
+      fieldBackground: "#fff",
+      fieldDescription: "#777",
+    },
+    dark: {
+      fieldBorder: "#333",
+      fieldFocusedBorder: "#88f",
+      fieldError: "#f66",
+      fieldText: "#eee",
+      fieldLabel: "#999",
+      fieldPlaceholder: "#999",
+      fieldBackground: "#000",
+      fieldDescription: "#aaa",
+    },
+  },
+};
+
+describe("resolveFieldColor", () => {
+  it("returns the explicit prop when provided", () => {
+    assert.equal(
+      resolveFieldColor("#abc", FIELD_THEME_ROLES.borderColor, null, "light"),
+      "#abc",
+    );
+  });
+
+  it("reads the theme role when the prop is omitted", () => {
+    assert.equal(
+      resolveFieldColor(
+        undefined,
+        FIELD_THEME_ROLES.borderColor,
+        ctx,
+        "light",
+      ),
+      "#aaa",
+    );
+    assert.equal(
+      resolveFieldColor(
+        undefined,
+        FIELD_THEME_ROLES.focusedBorderColor,
+        ctx,
+        "dark",
+      ),
+      "#88f",
+    );
+  });
+
+  it("throws when the prop is omitted and ThemeProvider is missing", () => {
+    assert.throws(
+      () =>
+        resolveFieldColor(
+          undefined,
+          FIELD_THEME_ROLES.textColor,
+          null,
+          "light",
+        ),
+      /ThemeProvider/,
+    );
+  });
+
+  it("throws when the theme role is missing", () => {
+    assert.throws(
+      () => resolveFieldColor(undefined, "missingRole", ctx, "light"),
+      /Unknown theme colour "missingRole"/,
+    );
+  });
+});
+
+describe("FIELD_THEME_ROLES", () => {
+  it("maps each colour prop to a field-prefixed theme role", () => {
+    assert.equal(FIELD_THEME_ROLES.borderColor, "fieldBorder");
+    assert.equal(FIELD_THEME_ROLES.focusedBorderColor, "fieldFocusedBorder");
+    assert.equal(FIELD_THEME_ROLES.errorColor, "fieldError");
+    assert.equal(FIELD_THEME_ROLES.textColor, "fieldText");
+    assert.equal(FIELD_THEME_ROLES.labelColor, "fieldLabel");
+    assert.equal(FIELD_THEME_ROLES.placeholderColor, "fieldPlaceholder");
+    assert.equal(FIELD_THEME_ROLES.backgroundColor, "fieldBackground");
+    assert.equal(FIELD_THEME_ROLES.descriptionColor, "fieldDescription");
+  });
+});

package/src/components/Field/resolveFieldColor.ts

@@ -0,0 +1,26 @@
+import type { ThemeContextValue } from "../../theme/types";
+
+/**
+ * Resolve a Field colour: explicit prop wins; otherwise read the theme role.
+ * Pure helper so it can be unit-tested without rendering.
+ */
+export function resolveFieldColor(
+  prop: string | undefined,
+  role: string,
+  ctx: ThemeContextValue | null,
+  scheme: "light" | "dark",
+): string {
+  if (prop != null) {
+    return prop;
+  }
+  if (!ctx) {
+    throw new Error(
+      `Field colour "${role}" was not passed and Field requires ThemeProvider to resolve defaults`,
+    );
+  }
+  const value = ctx.colors[scheme][role];
+  if (value == null) {
+    throw new Error(`Unknown theme colour "${role}" for scheme "${scheme}"`);
+  }
+  return value;
+}

package/src/components/Field/types.ts

@@ -0,0 +1,53 @@
+import type { ReactNode, Ref } from "react";
+import type {
+  StyleProp,
+  TextInputProps,
+  TextStyle,
+  ViewStyle,
+} from "react-native";
+import type { ButtonRadius } from "../Button/buttonRadius";
+
+export type FieldSharedProps = {
+  value: string;
+  onChangeText: (text: string) => void;
+  /** Defaults to theme role `fieldBorder`. */
+  borderColor?: string;
+  /** Defaults to theme role `fieldFocusedBorder`. */
+  focusedBorderColor?: string;
+  /** Defaults to theme role `fieldError`. */
+  errorColor?: string;
+  /** Defaults to theme role `fieldText`. */
+  textColor?: string;
+  /** Defaults to theme role `fieldLabel`. */
+  labelColor?: string;
+  /** Defaults to theme role `fieldPlaceholder`. */
+  placeholderColor?: string;
+  /** Defaults to theme role `fieldBackground`. */
+  backgroundColor?: string;
+  label?: string;
+  /** Helper text under the input. Hidden while `error` is set. */
+  description?: string;
+  error?: string;
+  placeholder?: string;
+  radius?: ButtonRadius;
+  editable?: boolean;
+  clearIcon?: ReactNode;
+  onClear?: () => void;
+  style?: StyleProp<ViewStyle>;
+  inputStyle?: StyleProp<TextStyle>;
+  /** Forwarded to TextInput; do not invert. */
+  secureTextEntry?: boolean;
+  keyboardType?: TextInputProps["keyboardType"];
+  autoCapitalize?: TextInputProps["autoCapitalize"];
+  autoComplete?: TextInputProps["autoComplete"];
+  textContentType?: TextInputProps["textContentType"];
+  onFocus?: TextInputProps["onFocus"];
+  onBlur?: TextInputProps["onBlur"];
+  ref?: Ref<import("react-native").TextInput>;
+};
+
+export type FieldTextProps = FieldSharedProps;
+
+export type FieldTextareaProps = FieldSharedProps & {
+  numberOfLines?: number;
+};

package/src/components/Field/useResolvedFieldColor.ts

@@ -0,0 +1,15 @@
+import { useContext } from "react";
+import { useColorScheme as useSystemColorScheme } from "react-native";
+import { resolveColorScheme } from "../../theme/resolveColorScheme";
+import { ThemeContext } from "../../theme/ThemeProvider";
+import { resolveFieldColor } from "./resolveFieldColor";
+
+export function useResolvedFieldColor(
+  prop: string | undefined,
+  role: string,
+): string {
+  const ctx = useContext(ThemeContext);
+  const systemScheme = useSystemColorScheme();
+  const scheme = resolveColorScheme(systemScheme);
+  return resolveFieldColor(prop, role, ctx, scheme);
+}

package/src/components/Form/Form.tsx

@@ -0,0 +1,205 @@
+import { useState, type ReactNode } from "react";
+import {
+  StyleSheet,
+  Text,
+  View,
+  type LayoutChangeEvent,
+} from "react-native";
+import {
+  KeyboardAwareScrollView,
+  KeyboardStickyView,
+} from "react-native-keyboard-controller";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { screenPaddingHorizontal } from "../../layout/screenPadding";
+import { Button } from "../Button/Button";
+import { FormCloseButton } from "./FormCloseButton";
+import type { FormProps } from "./types";
+import { useResolvedThemeColor } from "./useResolvedThemeColor";
+import { withAlpha } from "./withAlpha";
+
+/** How far the header wash continues below the buttons. */
+const FADE_TAIL = 32;
+
+/** Space kept between the focused field and the top of the footer. */
+const FIELD_GAP = 12;
+
+/**
+ * The scroll view lifts the caret, which sits inside the field. This covers
+ * the rest of the control below the caret so the rounded bottom stays visible.
+ */
+const FIELD_BELOW_CARET = 36;
+
+export function Form({
+  title,
+  children,
+  onClose,
+  onSubmit,
+  submitLabel = "Save",
+  submitting = false,
+  submitDisabled = false,
+  closeButton,
+  submitRadius = "lg",
+  paddingHorizontal = screenPaddingHorizontal,
+  backgroundColor: backgroundColorProp,
+  titleColor: titleColorProp,
+  footerBackgroundColor: footerBackgroundColorProp,
+  buttonBackgroundColor: buttonBackgroundColorProp,
+  buttonLabelColor: buttonLabelColorProp,
+}: FormProps) {
+  const insets = useSafeAreaInsets();
+  const background = useResolvedThemeColor(backgroundColorProp, "background");
+  const titleColor = useResolvedThemeColor(titleColorProp, "text");
+  const footerBackground = useResolvedThemeColor(
+    footerBackgroundColorProp,
+    "surface",
+  );
+  const buttonBackground = useResolvedThemeColor(
+    buttonBackgroundColorProp,
+    "buttonBackground",
+  );
+  const buttonLabel = useResolvedThemeColor(
+    buttonLabelColorProp,
+    "buttonLabel",
+  );
+  const [footerHeight, setFooterHeight] = useState(0);
+  const [cancelWidth, setCancelWidth] = useState(0);
+  const [barHeight, setBarHeight] = useState(0);
+  const resolvedBar = barHeight || insets.top + 52;
+
+  const onFooterLayout = (event: LayoutChangeEvent) => {
+    const next = Math.round(event.nativeEvent.layout.height);
+    setFooterHeight((current) => (current === next ? current : next));
+  };
+
+  const resolvedClose: ReactNode = closeButton ?? (
+    <FormCloseButton onPress={onClose} />
+  );
+
+  return (
+    <View style={[styles.screen, { backgroundColor: background }]}>
+      <KeyboardAwareScrollView
+        automaticallyAdjustKeyboardInsets={false}
+        bottomOffset={footerHeight + FIELD_GAP + FIELD_BELOW_CARET}
+        contentContainerStyle={[
+          styles.content,
+          {
+            paddingTop: resolvedBar + FADE_TAIL,
+            paddingHorizontal,
+          },
+        ]}
+        contentInsetAdjustmentBehavior="never"
+        keyboardDismissMode="interactive"
+        keyboardShouldPersistTaps="handled"
+        showsVerticalScrollIndicator={false}
+        style={styles.scroll}
+      >
+        {children}
+      </KeyboardAwareScrollView>
+
+      <View
+        pointerEvents="box-none"
+        style={[
+          styles.fade,
+          {
+            height: resolvedBar + FADE_TAIL,
+            experimental_backgroundImage: `linear-gradient(to bottom, ${withAlpha(background, 0.98)} 0%, ${withAlpha(background, 0.92)} 55%, ${withAlpha(background, 0)} 100%)`,
+          },
+        ]}
+      >
+        <View
+          onLayout={(event) => {
+            const next = Math.round(event.nativeEvent.layout.height);
+            setBarHeight((current) => (current === next ? current : next));
+          }}
+          pointerEvents="box-none"
+          style={[
+            styles.header,
+            { paddingTop: insets.top, paddingHorizontal },
+          ]}
+        >
+          <View
+            onLayout={(event) => {
+              const next = Math.round(event.nativeEvent.layout.width);
+              setCancelWidth((current) => (current === next ? current : next));
+            }}
+          >
+            {resolvedClose}
+          </View>
+          <Text
+            accessibilityRole="header"
+            numberOfLines={1}
+            pointerEvents="none"
+            style={[styles.title, { flex: 1, color: titleColor }]}
+          >
+            {title}
+          </Text>
+          <View style={{ width: cancelWidth }} />
+        </View>
+      </View>
+
+      {/*
+        The spacer is the home-indicator clearance. `opened` equals that
+        spacer, so once the keyboard is up the spacer sits inside the
+        keyboard and the button rests on whatever height the keyboard is.
+      */}
+      <KeyboardStickyView offset={{ closed: 0, opened: insets.bottom }}>
+        <View style={[styles.footerShell, { backgroundColor: footerBackground }]}>
+          <View
+            onLayout={onFooterLayout}
+            style={[styles.footer, { paddingHorizontal }]}
+          >
+            <Button
+              backgroundColor={buttonBackground}
+              disabled={submitDisabled}
+              label={submitLabel}
+              labelColor={buttonLabel}
+              loading={submitting}
+              onPress={onSubmit}
+              radius={submitRadius}
+            />
+          </View>
+          <View style={{ height: insets.bottom }} />
+        </View>
+      </KeyboardStickyView>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+  },
+  scroll: {
+    flex: 1,
+  },
+  content: {
+    paddingTop: 20,
+    paddingBottom: 24,
+  },
+  fade: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+  },
+  title: {
+    fontSize: 17,
+    fontWeight: "600",
+    textAlign: "center",
+  },
+  footerShell: {
+    // Cast upward so the sticky footer separates from the scroll body.
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: -4 },
+    shadowOpacity: 0.08,
+    shadowRadius: 12,
+    elevation: 8,
+  },
+  footer: {
+    paddingVertical: 12,
+  },
+});

package/src/components/Form/FormCloseButton.tsx

@@ -0,0 +1,19 @@
+import { Pressable, StyleSheet, Text } from "react-native";
+import { useThemeColor } from "../../theme/useThemeColor";
+
+export function FormCloseButton({ onPress }: { onPress: () => void }) {
+  const text = useThemeColor("text");
+
+  return (
+    <Pressable accessibilityRole="button" hitSlop={8} onPress={onPress}>
+      <Text style={[styles.label, { color: text }]}>Cancel</Text>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  label: {
+    fontSize: 17,
+    fontWeight: "600",
+  },
+});

package/src/components/Form/index.ts

@@ -0,0 +1,3 @@
+export { Form } from "./Form";
+export { FormCloseButton } from "./FormCloseButton";
+export type { FormProps } from "./types";

package/src/components/Form/resolveThemeColor.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve a colour: explicit prop wins; otherwise read the theme role.
+ * Pure helper so it can be unit-tested without rendering.
+ */
+export function resolveThemeColor(
+  prop: string | undefined,
+  role: string,
+  ctx: { colors: { light: Record<string, string>; dark: Record<string, string> } } | null,
+  scheme: "light" | "dark",
+): string {
+  if (prop != null) {
+    return prop;
+  }
+  if (!ctx) {
+    throw new Error(
+      `Colour "${role}" was not passed and ThemeProvider is required to resolve defaults`,
+    );
+  }
+  const value = ctx.colors[scheme][role];
+  if (value == null) {
+    throw new Error(`Unknown theme colour "${role}" for scheme "${scheme}"`);
+  }
+  return value;
+}

package/src/components/Form/types.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+import type { ButtonRadius } from "../Button/buttonRadius";
+
+export type FormProps = {
+  title: string;
+  children: ReactNode;
+  onClose: () => void;
+  onSubmit: () => void;
+  submitLabel?: string;
+  submitting?: boolean;
+  submitDisabled?: boolean;
+  /** App-specific Cancel control. Defaults to a plain text Cancel. */
+  closeButton?: ReactNode;
+  submitRadius?: ButtonRadius;
+  /**
+   * Horizontal inset for header, scroll content, and footer.
+   * Defaults to 16. Pass a value to override.
+   */
+  paddingHorizontal?: number;
+  /** Defaults to theme role `background`. */
+  backgroundColor?: string;
+  /** Defaults to theme role `text`. */
+  titleColor?: string;
+  /** Defaults to theme role `surface`. Footer ground. */
+  footerBackgroundColor?: string;
+  /** Defaults to theme role `buttonBackground`. */
+  buttonBackgroundColor?: string;
+  /** Defaults to theme role `buttonLabel`. */
+  buttonLabelColor?: string;
+};

package/src/components/Form/useResolvedThemeColor.ts

@@ -0,0 +1,15 @@
+import { useContext } from "react";
+import { useColorScheme as useSystemColorScheme } from "react-native";
+import { resolveColorScheme } from "../../theme/resolveColorScheme";
+import { ThemeContext } from "../../theme/ThemeProvider";
+import { resolveThemeColor } from "./resolveThemeColor";
+
+export function useResolvedThemeColor(
+  prop: string | undefined,
+  role: string,
+): string {
+  const ctx = useContext(ThemeContext);
+  const systemScheme = useSystemColorScheme();
+  const scheme = resolveColorScheme(systemScheme);
+  return resolveThemeColor(prop, role, ctx, scheme);
+}

package/src/components/Form/withAlpha.test.ts

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { withAlpha } from "./withAlpha.ts";
+
+describe("withAlpha", () => {
+  it("converts a hex colour to rgba", () => {
+    assert.equal(withAlpha("#EDE7DE", 0.98), "rgba(237, 231, 222, 0.98)");
+  });
+
+  it("expands three-digit hex", () => {
+    assert.equal(withAlpha("#abc", 0.5), "rgba(170, 187, 204, 0.5)");
+  });
+});

package/src/components/Form/withAlpha.ts

@@ -0,0 +1,9 @@
+export function withAlpha(hex: string, alpha: number): string {
+  const raw = hex.replace("#", "");
+  const full =
+    raw.length === 3 ? raw.split("").map((c) => `${c}${c}`).join("") : raw;
+  const r = Number.parseInt(full.slice(0, 2), 16);
+  const g = Number.parseInt(full.slice(2, 4), 16);
+  const b = Number.parseInt(full.slice(4, 6), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}