@forthtilliath/react-native-kit 0.5.0 → 0.6.0

package/README.md

@@ -204,6 +204,73 @@ confirmDestructive("Delete this item?", () => deleteItem(id), {
 });
 ```
 
+### `useEffectiveColorScheme(preference)`
+
+Resolves a `"light" | "dark" | "system"` theme preference against the device's color scheme: `"system"` follows the device, `"light"`/`"dark"` override it regardless of what the device is set to.
+
+```tsx
+import { useEffectiveColorScheme } from "@forthtilliath/react-native-kit/useEffectiveColorScheme";
+
+const scheme = useEffectiveColorScheme(themePreference); // "light" | "dark"
+const colors = scheme === "dark" ? darkColors : lightColors;
+```
+
+### `<ThemeToggle value onChange />`
+
+3-way segmented control for a light/dark/system theme preference.
+
+```tsx
+import { ThemeToggle } from "@forthtilliath/react-native-kit/ThemeToggle";
+
+<ThemeToggle value={themePreference} onChange={setThemePreference} />;
+```
+
+### `useUpdateCheck(options)`
+
+Checks once per mount (e.g. app launch) whether a newer release is available, throttled to at most one real check per `minIntervalMs` (default 12h) and silent for a release the user already dismissed. Has no opinion on where "when did we last check" / "which version did the user dismiss" are persisted — both are read/written entirely through the options you pass in.
+
+```tsx
+import { useUpdateCheck } from "@forthtilliath/react-native-kit/useUpdateCheck";
+
+const update = useUpdateCheck({
+  currentVersion: Constants.expoConfig?.version ?? "0.0.0",
+  checkForUpdate: fetchLatestRelease,
+  compareVersions,
+  getLastCheck: () => ({
+    lastCheckedAt: settings?.lastUpdateCheckAt ?? null,
+    dismissedVersion: settings?.dismissedUpdateVersion ?? null,
+  }),
+  onChecked: (lastCheckedAt) =>
+    updateSettings({ lastUpdateCheckAt: lastCheckedAt }),
+});
+
+if (update.status === "available") {
+  // update.release.version / .notes / .apkUrl
+}
+```
+
+### `<UpdateAvailableBanner version notes onPress onDismiss />`
+
+Dismissible banner announcing an available update: version, release notes (rendered via `ChangelogNotes`), an action button and a dismiss button. Has no opinion on what the action does (e.g. navigate to an update screen) or on how/whether dismissal is persisted.
+
+```tsx
+import { UpdateAvailableBanner } from "@forthtilliath/react-native-kit/UpdateAvailableBanner";
+
+{
+  update.status === "available" && (
+    <UpdateAvailableBanner
+      version={update.release.version}
+      notes={update.release.notes}
+      onPress={() => router.push("/settings/update")}
+      onDismiss={() => {
+        dismissUpdateVersion(update.release.version);
+        update.dismiss();
+      }}
+    />
+  );
+}
+```
+
 ### Utils (`utils/`)
 
 Framework-agnostic pure functions — no React or React Native import, usable from Node/web too.

package/dist/ThemeToggle.d.ts

@@ -0,0 +1,22 @@
+import type { StyleProp, TextStyle, ViewStyle } from "react-native";
+import type { ThemePreference } from "./useEffectiveColorScheme.js";
+export interface ThemeToggleStyles {
+    container?: StyleProp<ViewStyle>;
+    option?: StyleProp<ViewStyle>;
+    optionActive?: StyleProp<ViewStyle>;
+    optionText?: StyleProp<TextStyle>;
+    optionTextActive?: StyleProp<TextStyle>;
+}
+export interface ThemeToggleLabels {
+    light?: string;
+    dark?: string;
+    system?: string;
+}
+export interface ThemeToggleProps {
+    value: ThemePreference;
+    onChange: (preference: ThemePreference) => void;
+    labels?: ThemeToggleLabels;
+    styles?: ThemeToggleStyles;
+}
+export declare function ThemeToggle({ value, onChange, labels, styles, }: ThemeToggleProps): import("react").JSX.Element;
+//# sourceMappingURL=ThemeToggle.d.ts.map

package/dist/ThemeToggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeToggle.d.ts","sourceRoot":"","sources":["../src/ThemeToggle.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,YAAY,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAClC,gBAAgB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,CAAC,UAAU,EAAE,eAAe,KAAK,IAAI,CAAC;IAChD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AA2BD,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,GACP,EAAE,gBAAgB,+BA6BlB"}

package/dist/ThemeToggle.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Pressable, Text, View } from "react-native";
+const OPTIONS = ["light", "dark", "system"];
+const defaultStyles = {
+    container: { flexDirection: "row", gap: 8 },
+    option: {
+        flex: 1,
+        borderWidth: 1,
+        borderColor: "#e5e7eb",
+        borderRadius: 10,
+        paddingVertical: 10,
+        alignItems: "center",
+        backgroundColor: "#ffffff",
+    },
+    optionActive: { backgroundColor: "#2563eb", borderColor: "#2563eb" },
+    optionText: { fontSize: 15, fontWeight: "600", color: "#111827" },
+    optionTextActive: { color: "#ffffff" },
+};
+const defaultLabels = {
+    light: "Clair",
+    dark: "Sombre",
+    system: "Système",
+};
+// 3-way segmented control for a light/dark/system theme preference.
+export function ThemeToggle({ value, onChange, labels, styles, }) {
+    const merged = { ...defaultStyles, ...styles };
+    const t = { ...defaultLabels, ...labels };
+    return (_jsx(View, { style: merged.container, children: OPTIONS.map((option) => {
+            const active = option === value;
+            return (_jsx(Pressable, { style: [merged.option, active && merged.optionActive], onPress: () => {
+                    onChange(option);
+                }, accessibilityRole: "button", accessibilityState: { selected: active }, accessibilityLabel: t[option], children: _jsx(Text, { style: [merged.optionText, active && merged.optionTextActive], children: t[option] }) }, option));
+        }) }));
+}

package/dist/UpdateAvailableBanner.d.ts

@@ -0,0 +1,29 @@
+import type { StyleProp, TextStyle, ViewStyle } from "react-native";
+import type { ChangelogNotesStyles } from "./ChangelogNotes.js";
+export interface UpdateAvailableBannerStyles {
+    container?: StyleProp<ViewStyle>;
+    header?: StyleProp<ViewStyle>;
+    title?: StyleProp<TextStyle>;
+    notes?: ChangelogNotesStyles;
+    actionButton?: StyleProp<ViewStyle>;
+    actionButtonText?: StyleProp<TextStyle>;
+    dismissButton?: StyleProp<ViewStyle>;
+    dismissButtonText?: StyleProp<TextStyle>;
+}
+export interface UpdateAvailableBannerLabels {
+    title?: (version: string) => string;
+    action?: string;
+    dismiss?: string;
+    dismissAccessibilityLabel?: string;
+}
+export interface UpdateAvailableBannerProps {
+    version: string;
+    /** Raw release notes, passed straight to `ChangelogNotes`. */
+    notes: string;
+    onPress: () => void;
+    onDismiss: () => void;
+    labels?: UpdateAvailableBannerLabels;
+    styles?: UpdateAvailableBannerStyles;
+}
+export declare function UpdateAvailableBanner({ version, notes, onPress, onDismiss, labels, styles, }: UpdateAvailableBannerProps): import("react").JSX.Element;
+//# sourceMappingURL=UpdateAvailableBanner.d.ts.map

package/dist/UpdateAvailableBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UpdateAvailableBanner.d.ts","sourceRoot":"","sources":["../src/UpdateAvailableBanner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,MAAM,WAAW,2BAA2B;IAC1C,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,YAAY,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACpC,gBAAgB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACrC,iBAAiB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,2BAA2B,CAAC;IACrC,MAAM,CAAC,EAAE,2BAA2B,CAAC;CACtC;AAwCD,wBAAgB,qBAAqB,CAAC,EACpC,OAAO,EACP,KAAK,EACL,OAAO,EACP,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,0BAA0B,+BA4B5B"}

package/dist/UpdateAvailableBanner.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Pressable, Text, View } from "react-native";
+import { ChangelogNotes } from "./ChangelogNotes.js";
+const defaultStyles = {
+    container: {
+        backgroundColor: "#ffffff",
+        borderWidth: 1,
+        borderColor: "#e5e7eb",
+        borderRadius: 10,
+        padding: 14,
+        gap: 8,
+    },
+    header: {
+        flexDirection: "row",
+        justifyContent: "space-between",
+        alignItems: "center",
+    },
+    title: { fontSize: 15, fontWeight: "700", color: "#111827" },
+    notes: {},
+    actionButton: {
+        backgroundColor: "#2563eb",
+        borderRadius: 10,
+        paddingVertical: 10,
+        alignItems: "center",
+    },
+    actionButtonText: { color: "#ffffff", fontSize: 14, fontWeight: "700" },
+    dismissButton: { padding: 4 },
+    dismissButtonText: { fontSize: 13, color: "#6b7280" },
+};
+const defaultLabels = {
+    title: (version) => `Version ${version} disponible`,
+    action: "Voir",
+    dismiss: "Fermer",
+    dismissAccessibilityLabel: "Fermer la notification de mise à jour",
+};
+// Dismissible banner announcing an available update: version, release notes
+// (via `ChangelogNotes`), and an action + dismiss button. Has no opinion on
+// what "action" does (e.g. navigate to an update screen) or on how/whether
+// dismissal is persisted — both are left entirely to the caller.
+export function UpdateAvailableBanner({ version, notes, onPress, onDismiss, labels, styles, }) {
+    const merged = { ...defaultStyles, ...styles };
+    const t = { ...defaultLabels, ...labels };
+    return (_jsxs(View, { style: merged.container, children: [_jsxs(View, { style: merged.header, children: [_jsx(Text, { style: merged.title, children: t.title(version) }), _jsx(Pressable, { style: merged.dismissButton, onPress: onDismiss, accessibilityRole: "button", accessibilityLabel: t.dismissAccessibilityLabel, children: _jsx(Text, { style: merged.dismissButtonText, children: t.dismiss }) })] }), notes ? _jsx(ChangelogNotes, { notes: notes, styles: merged.notes }) : null, _jsx(Pressable, { style: merged.actionButton, onPress: onPress, accessibilityRole: "button", accessibilityLabel: t.action, children: _jsx(Text, { style: merged.actionButtonText, children: t.action }) })] }));
+}

package/dist/useEffectiveColorScheme.d.ts

@@ -0,0 +1,3 @@
+export type ThemePreference = "light" | "dark" | "system";
+export declare function useEffectiveColorScheme(preference: ThemePreference): "light" | "dark";
+//# sourceMappingURL=useEffectiveColorScheme.d.ts.map

package/dist/useEffectiveColorScheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEffectiveColorScheme.d.ts","sourceRoot":"","sources":["../src/useEffectiveColorScheme.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAM1D,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,eAAe,GAC1B,OAAO,GAAG,MAAM,CAIlB"}

package/dist/useEffectiveColorScheme.js

@@ -0,0 +1,11 @@
+import { useColorScheme } from "react-native";
+// Resolves a user's theme preference against the device's color scheme:
+// "system" follows the device, "light"/"dark" override it regardless of what
+// the device is set to. `useColorScheme()` can return `null` (unknown, e.g.
+// during the very first render on some platforms), treated as "light".
+export function useEffectiveColorScheme(preference) {
+    const systemScheme = useColorScheme();
+    if (preference !== "system")
+        return preference;
+    return systemScheme === "dark" ? "dark" : "light";
+}

package/dist/useUpdateCheck.d.ts

@@ -0,0 +1,35 @@
+export interface UpdateCheckRelease {
+    version: string;
+    notes: string;
+    apkUrl: string;
+}
+export type UpdateCheckState = {
+    status: "idle";
+} | {
+    status: "available";
+    release: UpdateCheckRelease;
+} | {
+    status: "error";
+};
+export interface UseUpdateCheckOptions {
+    /** The app's currently installed version, e.g. from its own version string. */
+    currentVersion: string;
+    /** Fetches the latest available release, or `null` if there is none. */
+    checkForUpdate: () => Promise<UpdateCheckRelease | null>;
+    /** Positive when `a` is newer than `b`, e.g. semver comparison. */
+    compareVersions: (a: string, b: string) => number;
+    /** Read once on mount: when the last check ran, and which version (if any) the user already dismissed. */
+    getLastCheck: () => {
+        lastCheckedAt: number | null;
+        dismissedVersion: string | null;
+    };
+    /** Called after each completed check (success or failure) so the caller can persist the timestamp. */
+    onChecked: (lastCheckedAt: number) => void;
+    /** Minimum delay between two checks. Defaults to 12h. */
+    minIntervalMs?: number;
+    now?: () => number;
+}
+export declare function useUpdateCheck({ currentVersion, checkForUpdate, compareVersions, getLastCheck, onChecked, minIntervalMs, now, }: UseUpdateCheckOptions): UpdateCheckState & {
+    dismiss: () => void;
+};
+//# sourceMappingURL=useUpdateCheck.d.ts.map

package/dist/useUpdateCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUpdateCheck.d.ts","sourceRoot":"","sources":["../src/useUpdateCheck.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GACpD;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAExB,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,cAAc,EAAE,MAAM,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACzD,mEAAmE;IACnE,eAAe,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,0GAA0G;IAC1G,YAAY,EAAE,MAAM;QAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,CAAC;IACF,sGAAsG;IACtG,SAAS,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD,wBAAgB,cAAc,CAAC,EAC7B,cAAc,EACd,cAAc,EACd,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAuC,EACvC,GAAc,GACf,EAAE,qBAAqB,GAAG,gBAAgB,GAAG;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAyCpE"}

package/dist/useUpdateCheck.js

@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react";
+const DEFAULT_MIN_INTERVAL_MS = 12 * 60 * 60 * 1000;
+// Checks once per mount (e.g. app launch) whether a newer release is
+// available, throttled to at most one real network check per `minIntervalMs`
+// and silent for a release the user already dismissed. Persistence of
+// "when did we last check" / "which version did the user dismiss" is left
+// entirely to the caller (`getLastCheck`/`onChecked`, plus its own dismiss
+// handler) — this hook has no opinion on where that lives.
+export function useUpdateCheck({ currentVersion, checkForUpdate, compareVersions, getLastCheck, onChecked, minIntervalMs = DEFAULT_MIN_INTERVAL_MS, now = Date.now, }) {
+    const [state, setState] = useState({ status: "idle" });
+    useEffect(() => {
+        const { lastCheckedAt, dismissedVersion } = getLastCheck();
+        if (lastCheckedAt != null && now() - lastCheckedAt < minIntervalMs)
+            return;
+        let cancelled = false;
+        checkForUpdate()
+            .then((release) => {
+            if (cancelled)
+                return;
+            onChecked(now());
+            if (release &&
+                compareVersions(release.version, currentVersion) > 0 &&
+                release.version !== dismissedVersion) {
+                setState({ status: "available", release });
+            }
+            else {
+                setState({ status: "idle" });
+            }
+        })
+            .catch(() => {
+            if (cancelled)
+                return;
+            onChecked(now());
+            setState({ status: "error" });
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps, @eslint-react/exhaustive-deps -- runs once per mount by design (e.g. once per app launch); options are expected to be stable for the caller's lifetime.
+    }, []);
+    return {
+        ...state,
+        dismiss: () => {
+            setState({ status: "idle" });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/react-native-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -43,8 +43,8 @@
     "react-test-renderer": "19.2.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@forthtilliath/typescript-config": "0.0.0",
-    "@forthtilliath/eslint-config": "0.0.0"
+    "@forthtilliath/eslint-config": "0.0.0",
+    "@forthtilliath/typescript-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",