@forthtilliath/react-native-kit 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @forthtilliath/react-native-kit
 
-Small, dependency-free-of-app-theme React Native UI components, distributed one file per component so consumers only pull in what they use.
+Small React Native building blocks — components, hooks, and framework-agnostic utils — with no opinion on your app's theme, distributed one file per export so consumers only pull in what they use.
 
 ## Install
 
@@ -70,6 +70,79 @@ The component ships with neutral default styles and no opinion on your app's the
 
 Every field of `styles` is optional — pass only the ones you want to override; the rest fall back to the defaults (`ChangelogNotesStyles` in `ChangelogNotes.tsx`).
 
+### `useSubmitGuard()`
+
+Prevents a second call while a first one is still pending — e.g. a double-tap on a "Save" button before it's had time to disable, which would otherwise create duplicate submissions.
+
+```tsx
+import { useSubmitGuard } from "@forthtilliath/react-native-kit/useSubmitGuard";
+
+const { isSaving, guard } = useSubmitGuard();
+
+<Pressable
+  disabled={isSaving}
+  onPress={() =>
+    guard(async () => {
+      await save();
+    })
+  }
+>
+  <Text>{isSaving ? "Saving…" : "Save"}</Text>
+</Pressable>;
+```
+
+### `useDebouncedChange(values, delayMs, callback)`
+
+Calls `callback` `delayMs` after the last change among `values`, ignoring renders where any value is still `undefined` (not loaded yet) and the very first render where they're all defined (no trigger on mount). A new change before the delay elapses resets the timer — a real debounce, not a throttle.
+
+```tsx
+import { useDebouncedChange } from "@forthtilliath/react-native-kit/useDebouncedChange";
+
+useDebouncedChange([settingsData, itemsData], 5 * 60 * 1000, () => {
+  runAutoBackup();
+});
+```
+
+### `confirmDestructive(title, onConfirm, options?)`
+
+Generic destructive-action confirmation (title + message + Cancel/Confirm), for anything irreversible (delete, reset...). Ships with French defaults (`message`, `cancelLabel`, `confirmLabel` all overridable).
+
+```ts
+import { confirmDestructive } from "@forthtilliath/react-native-kit/confirmDestructive";
+
+confirmDestructive("Delete this item?", () => deleteItem(id), {
+  message: "This cannot be undone.",
+  cancelLabel: "Cancel",
+  confirmLabel: "Delete",
+});
+```
+
+### Utils (`utils/`)
+
+Framework-agnostic pure functions — no React or React Native import, usable from Node/web too.
+
+```ts
+import { getPeriodStartMs } from "@forthtilliath/react-native-kit/utils/getPeriodStartMs";
+import { getMostRecentIds } from "@forthtilliath/react-native-kit/utils/getMostRecentIds";
+import { nextInCycle } from "@forthtilliath/react-native-kit/utils/nextInCycle";
+import { normalizeForSearch } from "@forthtilliath/react-native-kit/utils/normalizeForSearch";
+import { rankByNameMatch } from "@forthtilliath/react-native-kit/utils/rankByNameMatch";
+import { escapeCsvField } from "@forthtilliath/react-native-kit/utils/escapeCsvField";
+import { formatCsvNumber } from "@forthtilliath/react-native-kit/utils/formatCsvNumber";
+import { escapeHtml } from "@forthtilliath/react-native-kit/utils/escapeHtml";
+```
+
+| Function                                 | What it does                                                                                                                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `getPeriodStartMs(period, now?)`         | Start timestamp (ms) for a `"today" \| "7d" \| "30d" \| "all"` period filter, or `null` for `"all"`. `"today"` is the current calendar day, not a rolling 24h.     |
+| `getMostRecentIds(rows, limit?)`         | Most recently occurring distinct ids (`{ id, occurredAt }[]`), most recent first, deduplicated, limited (default 5).                                               |
+| `nextInCycle(ids, currentId)`            | Next id in a short list (e.g. cycling through recents on tap) — wraps to the first if `currentId` is at the end or no longer in the list.                          |
+| `normalizeForSearch(text)`               | Lowercases, trims, strips accents, and expands `œ`/`æ` ligatures (which `normalize("NFD")` alone doesn't decompose) — for accent/case-insensitive search matching. |
+| `rankByNameMatch(items, query, getName)` | Ranks `items` by relevance to `query`: earlier match position first, then shorter name — for a search-as-you-type list.                                            |
+| `escapeCsvField(value)`                  | Quotes and escapes a CSV field (RFC 4180) only if it contains a `"`, `;`, or newline.                                                                              |
+| `formatCsvNumber(value, decimals?)`      | Formats a number with a comma decimal separator (French-locale spreadsheets) instead of JS's dot.                                                                  |
+| `escapeHtml(text)`                       | Basic HTML entity escaping (`&`, `<`, `>`, `"`) for inserting user text into an HTML template.                                                                     |
+
 ## Scripts
 
 ```bash

package/dist/confirmDestructive.d.ts

@@ -0,0 +1,7 @@
+export interface ConfirmDestructiveOptions {
+    message?: string;
+    cancelLabel?: string;
+    confirmLabel?: string;
+}
+export declare function confirmDestructive(title: string, onConfirm: () => void, options?: ConfirmDestructiveOptions): void;
+//# sourceMappingURL=confirmDestructive.d.ts.map

package/dist/confirmDestructive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmDestructive.d.ts","sourceRoot":"","sources":["../src/confirmDestructive.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,IAAI,EACrB,OAAO,GAAE,yBAA8B,QAWxC"}

package/dist/confirmDestructive.js

@@ -0,0 +1,13 @@
+import { Alert } from "react-native";
+const DEFAULT_MESSAGE = "Cette action est définitive.";
+const DEFAULT_CANCEL_LABEL = "Annuler";
+const DEFAULT_CONFIRM_LABEL = "Supprimer";
+// Confirmation destructive générique (titre + message + Annuler/Confirmer),
+// pour toute action irréversible (suppression, réinitialisation...).
+export function confirmDestructive(title, onConfirm, options = {}) {
+    const { message = DEFAULT_MESSAGE, cancelLabel = DEFAULT_CANCEL_LABEL, confirmLabel = DEFAULT_CONFIRM_LABEL, } = options;
+    Alert.alert(title, message, [
+        { text: cancelLabel, style: "cancel" },
+        { text: confirmLabel, style: "destructive", onPress: onConfirm },
+    ]);
+}

package/dist/useDebouncedChange.d.ts

@@ -0,0 +1,2 @@
+export declare function useDebouncedChange(values: unknown[], delayMs: number, callback: () => void): void;
+//# sourceMappingURL=useDebouncedChange.d.ts.map

package/dist/useDebouncedChange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedChange.d.ts","sourceRoot":"","sources":["../src/useDebouncedChange.ts"],"names":[],"mappings":"AASA,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,IAAI,QAkBrB"}

package/dist/useDebouncedChange.js

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from "react";
+// Déclenche `callback` `delayMs` après le dernier changement parmi `values`,
+// en ignorant tout rendu tant qu'au moins une valeur vaut `undefined` (ex: une
+// donnée pas encore chargée) et le tout premier rendu où elles le sont toutes
+// (pour éviter un déclenchement au montage). Le délai est annulé si une
+// nouvelle valeur arrive avant qu'il n'expire (vrai debounce). `values` doit
+// avoir la même longueur à chaque rendu, comme pour un tableau de
+// dépendances de useEffect classique.
+export function useDebouncedChange(values, delayMs, callback) {
+    const hasInitializedRef = useRef(false);
+    useEffect(() => {
+        if (values.some((value) => value === undefined))
+            return;
+        if (!hasInitializedRef.current) {
+            hasInitializedRef.current = true;
+            return;
+        }
+        const timeout = setTimeout(callback, delayMs);
+        return () => {
+            clearTimeout(timeout);
+        };
+        // eslint-disable-next-line @eslint-react/exhaustive-deps, react-hooks/exhaustive-deps -- `values` IS the dependency list, by design (caller-provided, variable length not expected to change).
+    }, values);
+}

package/dist/useSubmitGuard.d.ts

@@ -0,0 +1,5 @@
+export declare function useSubmitGuard(): {
+    isSaving: boolean;
+    guard: (action: () => Promise<void>) => Promise<void>;
+};
+//# sourceMappingURL=useSubmitGuard.d.ts.map

package/dist/useSubmitGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSubmitGuard.d.ts","sourceRoot":"","sources":["../src/useSubmitGuard.ts"],"names":[],"mappings":"AAKA,wBAAgB,cAAc;;oBAGC,MAAM,OAAO,CAAC,IAAI,CAAC;EAWjD"}

package/dist/useSubmitGuard.js

@@ -0,0 +1,19 @@
+import { useState } from "react";
+// Empêche un second appel pendant qu'un premier est encore en cours (ex:
+// double-tap sur un bouton "Enregistrer" avant qu'il n'ait eu le temps de se
+// désactiver, qui créerait plusieurs soumissions identiques).
+export function useSubmitGuard() {
+    const [isSaving, setIsSaving] = useState(false);
+    async function guard(action) {
+        if (isSaving)
+            return;
+        setIsSaving(true);
+        try {
+            await action();
+        }
+        finally {
+            setIsSaving(false);
+        }
+    }
+    return { isSaving, guard };
+}

package/dist/utils/escapeCsvField.d.ts

@@ -0,0 +1,2 @@
+export declare function escapeCsvField(value: string): string;
+//# sourceMappingURL=escapeCsvField.d.ts.map

package/dist/utils/escapeCsvField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeCsvField.d.ts","sourceRoot":"","sources":["../../src/utils/escapeCsvField.ts"],"names":[],"mappings":"AAGA,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/utils/escapeCsvField.js

@@ -0,0 +1,8 @@
+// Échappe un champ CSV (RFC 4180) : entoure de guillemets et double les
+// guillemets internes si la valeur contient un guillemet, un point-virgule
+// (délimiteur) ou un saut de ligne — sinon la valeur est renvoyée telle quelle.
+export function escapeCsvField(value) {
+    if (!/[";\n]/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '""')}"`;
+}

package/dist/utils/escapeHtml.d.ts

@@ -0,0 +1,2 @@
+export declare function escapeHtml(text: string): string;
+//# sourceMappingURL=escapeHtml.d.ts.map

package/dist/utils/escapeHtml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeHtml.d.ts","sourceRoot":"","sources":["../../src/utils/escapeHtml.ts"],"names":[],"mappings":"AAEA,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/dist/utils/escapeHtml.js

@@ -0,0 +1,9 @@
+// Échappement HTML basique (esperluette, chevrons, guillemets) pour insérer
+// du texte utilisateur dans un gabarit HTML sans dépendance de templating.
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/dist/utils/formatCsvNumber.d.ts

@@ -0,0 +1,2 @@
+export declare function formatCsvNumber(value: number, decimals?: number): string;
+//# sourceMappingURL=formatCsvNumber.d.ts.map

package/dist/utils/formatCsvNumber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatCsvNumber.d.ts","sourceRoot":"","sources":["../../src/utils/formatCsvNumber.ts"],"names":[],"mappings":"AAGA,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAEnE"}

package/dist/utils/formatCsvNumber.js

@@ -0,0 +1,6 @@
+// Nombre brut (pas de suffixe d'unité) pour rester exploitable dans un
+// tableur (somme, moyenne...), avec la virgule décimale attendue par Excel
+// en locale française plutôt que le point de JS.
+export function formatCsvNumber(value, decimals = 1) {
+    return value.toFixed(decimals).replace(".", ",");
+}

package/dist/utils/getMostRecentIds.d.ts

@@ -0,0 +1,6 @@
+export interface RecentIdRow {
+    id: number | null;
+    occurredAt: string;
+}
+export declare function getMostRecentIds(rows: RecentIdRow[], limit?: number): number[];
+//# sourceMappingURL=getMostRecentIds.d.ts.map

package/dist/utils/getMostRecentIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMostRecentIds.d.ts","sourceRoot":"","sources":["../../src/utils/getMostRecentIds.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EAAE,EACnB,KAAK,SAAgB,GACpB,MAAM,EAAE,CAcV"}

package/dist/utils/getMostRecentIds.js

@@ -0,0 +1,19 @@
+const DEFAULT_LIMIT = 5;
+// Ids distincts les plus récents, du plus récent au plus ancien — utile pour
+// un sélecteur "récents" (aliment, récipient, ou tout autre entité datée).
+// `id` peut être null (référence supprimée depuis) : ignoré, on ne peut plus
+// le proposer.
+export function getMostRecentIds(rows, limit = DEFAULT_LIMIT) {
+    const sorted = [...rows].sort((a, b) => new Date(b.occurredAt).getTime() - new Date(a.occurredAt).getTime());
+    const seen = new Set();
+    const result = [];
+    for (const row of sorted) {
+        if (row.id == null || seen.has(row.id))
+            continue;
+        seen.add(row.id);
+        result.push(row.id);
+        if (result.length >= limit)
+            break;
+    }
+    return result;
+}

package/dist/utils/getPeriodStartMs.d.ts

@@ -0,0 +1,3 @@
+export type PeriodFilter = "all" | "today" | "7d" | "30d";
+export declare function getPeriodStartMs(period: PeriodFilter, now?: Date): number | null;
+//# sourceMappingURL=getPeriodStartMs.d.ts.map

package/dist/utils/getPeriodStartMs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPeriodStartMs.d.ts","sourceRoot":"","sources":["../../src/utils/getPeriodStartMs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,CAAC;AAK1D,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,GAAG,OAAa,GACf,MAAM,GAAG,IAAI,CASf"}

package/dist/utils/getPeriodStartMs.js

@@ -0,0 +1,14 @@
+// Timestamp (ms) à partir duquel un enregistrement est inclus pour cette
+// période, ou null pour "all" (pas de filtre de date). "today" part du début
+// du jour calendaire courant, pas d'il y a 24h glissantes.
+export function getPeriodStartMs(period, now = new Date()) {
+    if (period === "all")
+        return null;
+    if (period === "today") {
+        const startOfDay = new Date(now);
+        startOfDay.setHours(0, 0, 0, 0);
+        return startOfDay.getTime();
+    }
+    const days = period === "7d" ? 7 : 30;
+    return now.getTime() - days * 24 * 60 * 60 * 1000;
+}

package/dist/utils/nextInCycle.d.ts

@@ -0,0 +1,2 @@
+export declare function nextInCycle(ids: number[], currentId: number | null): number | null;
+//# sourceMappingURL=nextInCycle.d.ts.map

package/dist/utils/nextInCycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextInCycle.d.ts","sourceRoot":"","sources":["../../src/utils/nextInCycle.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EAAE,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,MAAM,GAAG,IAAI,CAIf"}

package/dist/utils/nextInCycle.js

@@ -0,0 +1,9 @@
+// Élément suivant dans une liste courte (ex: cycler sur tap entre quelques
+// éléments récents). Reprend au début si l'actuel n'y est plus (supprimé, ou
+// hors de la liste) ou si on est en bout de liste.
+export function nextInCycle(ids, currentId) {
+    if (ids.length === 0)
+        return null;
+    const currentIndex = currentId == null ? -1 : ids.indexOf(currentId);
+    return ids[(currentIndex + 1) % ids.length] ?? null;
+}

package/dist/utils/normalizeForSearch.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeForSearch(text: string): string;
+//# sourceMappingURL=normalizeForSearch.d.ts.map

package/dist/utils/normalizeForSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeForSearch.d.ts","sourceRoot":"","sources":["../../src/utils/normalizeForSearch.ts"],"names":[],"mappings":"AASA,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvD"}

package/dist/utils/normalizeForSearch.js

@@ -0,0 +1,15 @@
+// Les ligatures œ/æ ne se décomposent PAS via normalize("NFD") (contrairement
+// aux lettres accentuées) : ce sont des lettres Unicode à part entière, pas
+// une base + un signe combinant. Sans ce remplacement explicite, chercher
+// "Œuf" (avec la vraie ligature) ne trouve jamais "Oeuf" dans une base qui
+// l'orthographie sans ligature (comme la plupart des bases de données texte).
+function expandLigatures(text) {
+    return text.replace(/[œŒ]/g, "oe").replace(/[æÆ]/g, "ae");
+}
+export function normalizeForSearch(text) {
+    return expandLigatures(text)
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .trim();
+}

package/dist/utils/rankByNameMatch.d.ts

@@ -0,0 +1,2 @@
+export declare function rankByNameMatch<T>(items: T[], query: string, getName: (item: T) => string): T[];
+//# sourceMappingURL=rankByNameMatch.d.ts.map

package/dist/utils/rankByNameMatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rankByNameMatch.d.ts","sourceRoot":"","sources":["../../src/utils/rankByNameMatch.ts"],"names":[],"mappings":"AAsBA,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC3B,CAAC,EAAE,CAiBL"}

package/dist/utils/rankByNameMatch.js

@@ -0,0 +1,33 @@
+import { normalizeForSearch } from "./normalizeForSearch.js";
+// Cache le nom normalisé de chaque élément par référence d'objet : utile pour
+// des listes figées (constantes de module) cherchées à chaque frappe clavier
+// dans un champ de recherche, pour éviter de renormaliser tous les noms à
+// chaque appel.
+const normalizedNameCache = new WeakMap();
+function getNormalizedName(item, getName) {
+    if (typeof item !== "object" || item === null)
+        return normalizeForSearch(getName(item));
+    const cached = normalizedNameCache.get(item);
+    if (cached !== undefined)
+        return cached;
+    const normalized = normalizeForSearch(getName(item));
+    normalizedNameCache.set(item, normalized);
+    return normalized;
+}
+// Classe des éléments par pertinence vis-à-vis d'une recherche texte :
+// position du match dans le nom (plus tôt = plus pertinent), puis longueur
+// du nom. Générique pour être réutilisable par n'importe quelle liste
+// d'éléments ayant un nom affichable.
+export function rankByNameMatch(items, query, getName) {
+    const normalizedQuery = normalizeForSearch(query);
+    const matches = [];
+    for (const item of items) {
+        const matchIndex = getNormalizedName(item, getName).indexOf(normalizedQuery);
+        if (matchIndex !== -1) {
+            matches.push({ item, matchIndex });
+        }
+    }
+    matches.sort((a, b) => a.matchIndex - b.matchIndex ||
+        getName(a.item).length - getName(b.item).length);
+    return matches.map((m) => m.item);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/react-native-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {