@forthtilliath/react-native-kit 0.15.1 → 0.16.0

package/dist/index.d.ts

@@ -1,26 +1,46 @@
+export * from "./components/feedback/ErrorFallback.js";
+export * from "./components/list/AddButton.js";
 export * from "./components/list/ColorDot.js";
+export * from "./components/list/DragHandle.js";
 export * from "./components/list/SwipeableRow.js";
 export * from "./components/list/Thumbnail.js";
 export * from "./components/list/UndoToast.js";
+export * from "./components/overlay/BottomSheet.js";
+export * from "./components/picker/CheckboxGroup.js";
+export * from "./components/picker/MonthDayGrid.js";
+export * from "./components/picker/OptionsModal.js";
 export * from "./components/picker/PhotoPicker.js";
 export * from "./components/picker/PickerModal.js";
+export * from "./components/picker/QuantityStepper.js";
+export * from "./components/picker/SegmentedToggle.js";
+export * from "./components/picker/SelectField.js";
 export * from "./components/picker/VoiceSearchButton.js";
 export * from "./components/settings/AboutSettingsScreen.js";
 export * from "./components/settings/BackupSettingsScreen.js";
 export * from "./components/settings/ContactSettingsScreen.js";
 export * from "./components/settings/PrivacySettingsScreen.js";
+export * from "./components/settings/SettingsCard.js";
 export * from "./components/settings/SettingsMenu.js";
+export * from "./components/settings/SwitchRow.js";
 export * from "./components/settings/ThemeSettingsScreen.js";
 export * from "./components/settings/UpdateSettingsScreen.js";
 export * from "./components/theme/ThemeOptionList.js";
+export * from "./components/theme/themePreferenceContext.js";
+export * from "./components/theme/ThemePreferenceProvider.js";
 export * from "./components/theme/ThemeToggle.js";
 export * from "./hooks/useDebouncedChange.js";
 export * from "./hooks/useEffectiveColorScheme.js";
 export * from "./hooks/useSubmitGuard.js";
 export * from "./i18n/KitLocaleProvider.js";
 export * from "./i18n/locale.js";
+export * from "./utils/calendar/syncDedicatedCalendar.js";
+export * from "./utils/calendar/toCalendarEventDetails.js";
 export * from "./utils/helpers/confirmDestructive.js";
+export * from "./utils/helpers/haptics.js";
+export * from "./utils/helpers/isNativeModuleAvailable.js";
 export * from "./utils/helpers/mergeSlotStyles.js";
+export * from "./utils/helpers/shareFile.js";
+export * from "./utils/helpers/shareTextFile.js";
 export { getMostRecentIds, type RecentIdRow, } from "@forthtilliath/ts-kit/array/getMostRecentIds";
 export { nextInCycle } from "@forthtilliath/ts-kit/array/nextInCycle";
 export { rankByNameMatch } from "@forthtilliath/ts-kit/array/rankByNameMatch";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,OAAO,EACL,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,wCAAwC,CAAC;AACvD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC;AACrD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,2CAA2C,CAAC;AAC1D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,uCAAuC,CAAC;AACtD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AAGjD,OAAO,EACL,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC"}

package/dist/index.js

@@ -3,29 +3,49 @@
 // etc.) remain the recommended default for apps that want to avoid pulling in
 // peer deps they don't have installed (Metro doesn't reliably tree-shake) —
 // see the README.
+export * from "./components/feedback/ErrorFallback.js";
+export * from "./components/list/AddButton.js";
 export * from "./components/list/ColorDot.js";
+export * from "./components/list/DragHandle.js";
 export * from "./components/list/SwipeableRow.js";
 export * from "./components/list/Thumbnail.js";
 export * from "./components/list/UndoToast.js";
+export * from "./components/overlay/BottomSheet.js";
+export * from "./components/picker/CheckboxGroup.js";
+export * from "./components/picker/MonthDayGrid.js";
+export * from "./components/picker/OptionsModal.js";
 export * from "./components/picker/PhotoPicker.js";
 export * from "./components/picker/PickerModal.js";
+export * from "./components/picker/QuantityStepper.js";
+export * from "./components/picker/SegmentedToggle.js";
+export * from "./components/picker/SelectField.js";
 export * from "./components/picker/VoiceSearchButton.js";
 export * from "./components/settings/AboutSettingsScreen.js";
 export * from "./components/settings/BackupSettingsScreen.js";
 export * from "./components/settings/ContactSettingsScreen.js";
 export * from "./components/settings/PrivacySettingsScreen.js";
+export * from "./components/settings/SettingsCard.js";
 export * from "./components/settings/SettingsMenu.js";
+export * from "./components/settings/SwitchRow.js";
 export * from "./components/settings/ThemeSettingsScreen.js";
 export * from "./components/settings/UpdateSettingsScreen.js";
 export * from "./components/theme/ThemeOptionList.js";
+export * from "./components/theme/themePreferenceContext.js";
+export * from "./components/theme/ThemePreferenceProvider.js";
 export * from "./components/theme/ThemeToggle.js";
 export * from "./hooks/useDebouncedChange.js";
 export * from "./hooks/useEffectiveColorScheme.js";
 export * from "./hooks/useSubmitGuard.js";
 export * from "./i18n/KitLocaleProvider.js";
 export * from "./i18n/locale.js";
+export * from "./utils/calendar/syncDedicatedCalendar.js";
+export * from "./utils/calendar/toCalendarEventDetails.js";
 export * from "./utils/helpers/confirmDestructive.js";
+export * from "./utils/helpers/haptics.js";
+export * from "./utils/helpers/isNativeModuleAvailable.js";
 export * from "./utils/helpers/mergeSlotStyles.js";
+export * from "./utils/helpers/shareFile.js";
+export * from "./utils/helpers/shareTextFile.js";
 // Framework-agnostic — actually implemented (and tested/documented) in
 // ts-kit, re-exported here so existing imports of these names keep working.
 export { getMostRecentIds, } from "@forthtilliath/ts-kit/array/getMostRecentIds";

package/dist/utils/calendar/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./syncDedicatedCalendar.js";
+export * from "./toCalendarEventDetails.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/calendar/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/calendar/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC"}

package/dist/utils/calendar/index.js

@@ -0,0 +1,2 @@
+export * from "./syncDedicatedCalendar.js";
+export * from "./toCalendarEventDetails.js";

package/dist/utils/calendar/syncDedicatedCalendar.d.ts

@@ -0,0 +1,37 @@
+import type { CalendarEventDetails } from "./toCalendarEventDetails.js";
+/** The app's own calendar on the phone. */
+export interface DedicatedCalendar {
+    /** Internal name (Android), stable: finds the calendar again on the next sync. */
+    name: string;
+    /** Shown in the user's calendar app. */
+    title: string;
+    color: string;
+}
+export interface SyncDedicatedCalendarOptions {
+    calendar: DedicatedCalendar;
+    /** Start of the period to replace (included). */
+    from: Date;
+    /** End of the period to replace (excluded). */
+    to: Date;
+    /** The period's new events — see `toCalendarEventDetails`. */
+    events: readonly CalendarEventDetails[];
+}
+export type CalendarSyncResult = {
+    status: "denied";
+} | {
+    status: "done";
+    count: number;
+};
+/**
+ * Writes a period's events to the app's dedicated calendar on the phone
+ * (created on first use, as a local account), replacing whatever that
+ * calendar held over the period: a new sync replaces the previous one with no
+ * duplicates, and an event removed from the app disappears from the calendar
+ * too. Other calendars are never touched. Asks for the calendar permission
+ * first. Needs `expo-calendar` (an optional peer dependency).
+ *
+ * @param options - See {@link SyncDedicatedCalendarOptions}.
+ * @returns `{ status: "denied" }` without the permission, else the number of events written.
+ */
+export declare function syncDedicatedCalendar({ calendar, from, to, events, }: SyncDedicatedCalendarOptions): Promise<CalendarSyncResult>;
+//# sourceMappingURL=syncDedicatedCalendar.d.ts.map

package/dist/utils/calendar/syncDedicatedCalendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncDedicatedCalendar.d.ts","sourceRoot":"","sources":["../../../src/utils/calendar/syncDedicatedCalendar.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExE,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iDAAiD;IACjD,IAAI,EAAE,IAAI,CAAC;IACX,+CAA+C;IAC/C,EAAE,EAAE,IAAI,CAAC;IACT,8DAA8D;IAC9D,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,kBAAkB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAwB3D;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,QAAQ,EACR,IAAI,EACJ,EAAE,EACF,MAAM,GACP,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAY5D"}

package/dist/utils/calendar/syncDedicatedCalendar.js

@@ -0,0 +1,42 @@
+import * as Calendar from "expo-calendar";
+async function getOrCreateLocalCalendar({ name, title, color, }) {
+    const calendars = await Calendar.getCalendars(Calendar.EntityTypes.EVENT);
+    const existing = calendars.find((c) => c.name === name);
+    if (existing)
+        return existing;
+    return Calendar.createCalendar({
+        title,
+        name,
+        color,
+        entityType: Calendar.EntityTypes.EVENT,
+        // A local account: nothing syncs to a Google account, and the user can
+        // hide this calendar in one tap from their calendar app.
+        source: { isLocalAccount: true, name: title, type: "LOCAL" },
+        ownerAccount: title,
+        accessLevel: Calendar.CalendarAccessLevel.OWNER,
+    });
+}
+/**
+ * Writes a period's events to the app's dedicated calendar on the phone
+ * (created on first use, as a local account), replacing whatever that
+ * calendar held over the period: a new sync replaces the previous one with no
+ * duplicates, and an event removed from the app disappears from the calendar
+ * too. Other calendars are never touched. Asks for the calendar permission
+ * first. Needs `expo-calendar` (an optional peer dependency).
+ *
+ * @param options - See {@link SyncDedicatedCalendarOptions}.
+ * @returns `{ status: "denied" }` without the permission, else the number of events written.
+ */
+export async function syncDedicatedCalendar({ calendar, from, to, events, }) {
+    const { granted } = await Calendar.requestCalendarPermissions();
+    if (!granted)
+        return { status: "denied" };
+    const target = await getOrCreateLocalCalendar(calendar);
+    for (const event of await target.listEvents(from, to)) {
+        await event.delete();
+    }
+    for (const event of events) {
+        await target.createEvent(event);
+    }
+    return { status: "done", count: events.length };
+}

package/dist/utils/calendar/toCalendarEventDetails.d.ts

@@ -0,0 +1,32 @@
+/** A calendar event as an app describes it: a day, and optional wall-clock hours. */
+export interface CalendarEventInput {
+    title: string;
+    notes?: string;
+    /** The day, `YYYY-MM-DD`. */
+    date: string;
+    /** `HH:MM`; without `start` and `end` the event lasts all day. */
+    start?: string;
+    /** `HH:MM`; at or before `start`, the event ends the next day (night shift). */
+    end?: string;
+}
+/** What `expo-calendar`'s `createEvent` expects. */
+export interface CalendarEventDetails {
+    title: string;
+    notes: string;
+    startDate: Date;
+    endDate: Date;
+    allDay: boolean;
+    timeZone: string;
+}
+/**
+ * Converts an app event to `expo-calendar`'s format. Timed events are in
+ * local time and may end the next day; an all-day event is set at UTC
+ * midnight with the `"UTC"` time zone — what Android requires, otherwise it
+ * shows up a day off depending on the device's time zone.
+ *
+ * @param event - See {@link CalendarEventInput}.
+ * @param timeZone - Time zone of timed events. @defaultValue the device's
+ * @returns The details to pass to `calendar.createEvent()`.
+ */
+export declare function toCalendarEventDetails(event: CalendarEventInput, timeZone?: string): CalendarEventDetails;
+//# sourceMappingURL=toCalendarEventDetails.d.ts.map

package/dist/utils/calendar/toCalendarEventDetails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toCalendarEventDetails.d.ts","sourceRoot":"","sources":["../../../src/utils/calendar/toCalendarEventDetails.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAsBD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,GAAE,MAAyB,GAClC,oBAAoB,CAoBtB"}

package/dist/utils/calendar/toCalendarEventDetails.js

@@ -0,0 +1,47 @@
+function deviceTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+function nextDay(isoDate) {
+    const day = new Date(`${isoDate}T00:00:00Z`);
+    day.setUTCDate(day.getUTCDate() + 1);
+    return day.toISOString().slice(0, 10);
+}
+function localDateTime(isoDate, time) {
+    const [year = 0, month = 1, day = 1] = isoDate.split("-").map(Number);
+    const [hours = 0, minutes = 0] = time.split(":").map(Number);
+    return new Date(year, month - 1, day, hours, minutes);
+}
+function utcMidnight(isoDate) {
+    return new Date(`${isoDate}T00:00:00Z`);
+}
+/**
+ * Converts an app event to `expo-calendar`'s format. Timed events are in
+ * local time and may end the next day; an all-day event is set at UTC
+ * midnight with the `"UTC"` time zone — what Android requires, otherwise it
+ * shows up a day off depending on the device's time zone.
+ *
+ * @param event - See {@link CalendarEventInput}.
+ * @param timeZone - Time zone of timed events. @defaultValue the device's
+ * @returns The details to pass to `calendar.createEvent()`.
+ */
+export function toCalendarEventDetails(event, timeZone = deviceTimeZone()) {
+    if (event.start && event.end) {
+        const endDay = event.end <= event.start ? nextDay(event.date) : event.date;
+        return {
+            title: event.title,
+            notes: event.notes ?? "",
+            startDate: localDateTime(event.date, event.start),
+            endDate: localDateTime(endDay, event.end),
+            allDay: false,
+            timeZone,
+        };
+    }
+    return {
+        title: event.title,
+        notes: event.notes ?? "",
+        startDate: utcMidnight(event.date),
+        endDate: utcMidnight(nextDay(event.date)),
+        allDay: true,
+        timeZone: "UTC",
+    };
+}

package/dist/utils/files/appFiles.d.ts

@@ -0,0 +1,61 @@
+import { Directory } from "expo-file-system";
+/**
+ * The app's persistent sub-folder `name` (in documents), created on first use.
+ * `name` is made of letters, digits, `_`, `-`, and `/` between nested folders.
+ *
+ * @throws if `name` holds any other character (`..`, a leading `/`…).
+ */
+export declare function getAppDirectory(name: string): Directory;
+/**
+ * Extension of a file URI, query string ignored — `fallback` when it has none
+ * (picker URIs don't always carry one).
+ */
+export declare function getFileExtension(uri: string, fallback?: string): string;
+export interface PersistFileOptions {
+    /** Persistent sub-folder, see `getAppDirectory`. */
+    directory: string;
+    /** Start of the new file name (letters, digits, `_`, `-`), followed by a timestamp. */
+    prefix: string;
+}
+/**
+ * Copies a temporary file (picker result, download) into the persistent
+ * sub-folder and returns the copy's URI, to store instead of the original.
+ */
+export declare function persistFile(sourceUri: string, { directory, prefix }: PersistFileOptions): Promise<string>;
+export interface WriteBase64FileOptions extends PersistFileOptions {
+    /** @defaultValue "jpg" */
+    extension?: string;
+}
+/**
+ * Writes base64 content (a photo embedded in a JSON backup…) as a new file of
+ * the persistent sub-folder and returns its URI. Names are random rather than
+ * timestamped: a restore writes many files within the same millisecond.
+ *
+ * @throws if `directory`, `prefix` or `extension` isn't a plain name (see
+ * {@link getAppDirectory}).
+ */
+export declare function writeBase64File(base64: string, { directory, prefix, extension }: WriteBase64FileOptions): string;
+/**
+ * Content of a file as base64 (to embed it in a JSON backup), `null` when it
+ * can't be read — a photo the OS already cleared from its cache, a bad URI.
+ */
+export declare function readFileBase64(uri: string): string | null;
+/** Whether a file exists at `uri`; `false` for a malformed URI instead of throwing. */
+export declare function fileExists(uri: string): boolean;
+/**
+ * Deletes a file if it is still there, best effort: an absent file or a failed
+ * deletion never makes the caller fail.
+ */
+export declare function deleteFileQuietly(uri: string | null | undefined): void;
+/**
+ * Deletes every file of the persistent sub-folder that isn't in `keep`
+ * (replaced photo, deleted entity, data replaced by an import). Returns how
+ * many files were deleted.
+ *
+ * Files are matched by **name**, not by full URI: Android reaches the same
+ * file as `/data/user/0/<package>/…` or `/data/data/<package>/…` depending on
+ * the API that built the URI — compared as a whole, a stored URI in the other
+ * form would get its photo deleted.
+ */
+export declare function pruneAppDirectory(name: string, keep: Iterable<string>): number;
+//# sourceMappingURL=appFiles.d.ts.map

package/dist/utils/files/appFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appFiles.d.ts","sourceRoot":"","sources":["../../../src/utils/files/appFiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAe,MAAM,kBAAkB,CAAC;AA0B1D;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAQvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,CAGtE;AAED,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,kBAAkB,GACxC,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,EAAE,SAAS,EAAE,MAAM,EAAE,SAAiB,EAAE,EAAE,sBAAsB,GAC/D,MAAM,CAQR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMzD;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM/C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAQtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,GACrB,MAAM,CAcR"}

package/dist/utils/files/appFiles.js

@@ -0,0 +1,126 @@
+import { Directory, File, Paths } from "expo-file-system";
+import { randomId } from "@forthtilliath/ts-kit/id/randomId";
+// Files the app keeps for good (photos, avatars...): pickers and exports hand
+// back URIs in a cache folder the OS may empty at any time, so anything worth
+// keeping is copied into a sub-folder of the app's documents.
+// Folder names, prefixes and extensions end up in a path, and callers may
+// build them from imported data (a restored backup): only plain name
+// characters get through — no "..", no way out of the documents folder.
+const SAFE_NAME = /^[\w-]+$/;
+const SAFE_FOLDER = /^[\w-]+(\/[\w-]+)*$/;
+function assertSafe(value, pattern, what) {
+    if (!pattern.test(value)) {
+        throw new Error(`Invalid ${what}: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/** Last segment of a URI, i.e. the file name. */
+function fileNameOf(uri) {
+    return uri.slice(uri.lastIndexOf("/") + 1);
+}
+/**
+ * The app's persistent sub-folder `name` (in documents), created on first use.
+ * `name` is made of letters, digits, `_`, `-`, and `/` between nested folders.
+ *
+ * @throws if `name` holds any other character (`..`, a leading `/`…).
+ */
+export function getAppDirectory(name) {
+    const directory = new Directory(Paths.document, assertSafe(name, SAFE_FOLDER, "folder name"));
+    if (!directory.exists)
+        directory.create({ intermediates: true, idempotent: true });
+    return directory;
+}
+/**
+ * Extension of a file URI, query string ignored — `fallback` when it has none
+ * (picker URIs don't always carry one).
+ */
+export function getFileExtension(uri, fallback = "jpg") {
+    const match = uri.split("?")[0]?.match(/\.(\w+)$/);
+    return match?.[1] ?? fallback;
+}
+/**
+ * Copies a temporary file (picker result, download) into the persistent
+ * sub-folder and returns the copy's URI, to store instead of the original.
+ */
+export async function persistFile(sourceUri, { directory, prefix }) {
+    const destination = new File(getAppDirectory(directory), `${assertSafe(prefix, SAFE_NAME, "prefix")}-${Date.now()}.${getFileExtension(sourceUri)}`);
+    await new File(sourceUri).copy(destination);
+    return destination.uri;
+}
+/**
+ * Writes base64 content (a photo embedded in a JSON backup…) as a new file of
+ * the persistent sub-folder and returns its URI. Names are random rather than
+ * timestamped: a restore writes many files within the same millisecond.
+ *
+ * @throws if `directory`, `prefix` or `extension` isn't a plain name (see
+ * {@link getAppDirectory}).
+ */
+export function writeBase64File(base64, { directory, prefix, extension = "jpg" }) {
+    const file = new File(getAppDirectory(directory), `${assertSafe(prefix, SAFE_NAME, "prefix")}-${randomId()}.${assertSafe(extension, SAFE_NAME, "extension")}`);
+    file.create();
+    file.write(base64, { encoding: "base64" });
+    return file.uri;
+}
+/**
+ * Content of a file as base64 (to embed it in a JSON backup), `null` when it
+ * can't be read — a photo the OS already cleared from its cache, a bad URI.
+ */
+export function readFileBase64(uri) {
+    try {
+        return new File(uri).base64Sync();
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a file exists at `uri`; `false` for a malformed URI instead of throwing. */
+export function fileExists(uri) {
+    try {
+        return new File(uri).exists;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Deletes a file if it is still there, best effort: an absent file or a failed
+ * deletion never makes the caller fail.
+ */
+export function deleteFileQuietly(uri) {
+    if (!uri)
+        return;
+    try {
+        const file = new File(uri);
+        if (file.exists)
+            file.delete();
+    }
+    catch {
+        // Nothing to do: a leftover file is harmless.
+    }
+}
+/**
+ * Deletes every file of the persistent sub-folder that isn't in `keep`
+ * (replaced photo, deleted entity, data replaced by an import). Returns how
+ * many files were deleted.
+ *
+ * Files are matched by **name**, not by full URI: Android reaches the same
+ * file as `/data/user/0/<package>/…` or `/data/data/<package>/…` depending on
+ * the API that built the URI — compared as a whole, a stored URI in the other
+ * form would get its photo deleted.
+ */
+export function pruneAppDirectory(name, keep) {
+    const kept = new Set(Array.from(keep, fileNameOf));
+    let deleted = 0;
+    for (const entry of getAppDirectory(name).list()) {
+        if (entry instanceof File && !kept.has(fileNameOf(entry.uri))) {
+            try {
+                entry.delete();
+                deleted += 1;
+            }
+            catch {
+                // Retried on the next prune.
+            }
+        }
+    }
+    return deleted;
+}

package/dist/utils/files/imageThumbnail.d.ts

@@ -0,0 +1,22 @@
+import { type PersistFileOptions } from "./appFiles.js";
+export interface SaveImageThumbnailOptions extends PersistFileOptions {
+    /** Width in pixels, height keeps the ratio. @defaultValue 256 */
+    width?: number;
+    /** JPEG quality, 0 to 1. @defaultValue 0.8 */
+    quality?: number;
+}
+/**
+ * Shrinks a picked photo to a JPEG thumbnail and keeps it in the app's
+ * persistent sub-folder (see `getAppDirectory`); returns its URI. Small
+ * enough to embed as base64 in a JSON backup (`readFileBase64`) and recreate
+ * on restore (`writeBase64File`). Needs `expo-image-manipulator` and
+ * `expo-file-system`.
+ *
+ * @example
+ * const avatarUri = await saveImageThumbnail(pickedUri, {
+ *   directory: "avatars",
+ *   prefix: "avatar",
+ * });
+ */
+export declare function saveImageThumbnail(sourceUri: string, { width, quality, ...target }: SaveImageThumbnailOptions): Promise<string>;
+//# sourceMappingURL=imageThumbnail.d.ts.map

package/dist/utils/files/imageThumbnail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageThumbnail.d.ts","sourceRoot":"","sources":["../../../src/utils/files/imageThumbnail.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,kBAAkB,EAAmB,MAAM,eAAe,CAAC;AAEzE,MAAM,WAAW,yBAA0B,SAAQ,kBAAkB;IACnE,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,EAAE,KAAW,EAAE,OAAa,EAAE,GAAG,MAAM,EAAE,EAAE,yBAAyB,GACnE,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/utils/files/imageThumbnail.js

@@ -0,0 +1,28 @@
+import { ImageManipulator, SaveFormat } from "expo-image-manipulator";
+import { writeBase64File } from "./appFiles.js";
+/**
+ * Shrinks a picked photo to a JPEG thumbnail and keeps it in the app's
+ * persistent sub-folder (see `getAppDirectory`); returns its URI. Small
+ * enough to embed as base64 in a JSON backup (`readFileBase64`) and recreate
+ * on restore (`writeBase64File`). Needs `expo-image-manipulator` and
+ * `expo-file-system`.
+ *
+ * @example
+ * const avatarUri = await saveImageThumbnail(pickedUri, {
+ *   directory: "avatars",
+ *   prefix: "avatar",
+ * });
+ */
+export async function saveImageThumbnail(sourceUri, { width = 256, quality = 0.8, ...target }) {
+    const image = await ImageManipulator.manipulate(sourceUri)
+        .resize({ width })
+        .renderAsync();
+    const result = await image.saveAsync({
+        base64: true,
+        compress: quality,
+        format: SaveFormat.JPEG,
+    });
+    if (!result.base64)
+        throw new Error("Empty image");
+    return writeBase64File(result.base64, { ...target, extension: "jpg" });
+}

package/dist/utils/files/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./appFiles.js";
+export * from "./imageThumbnail.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC"}

package/dist/utils/files/index.js

@@ -0,0 +1,2 @@
+export * from "./appFiles.js";
+export * from "./imageThumbnail.js";

package/dist/utils/helpers/haptics.d.ts

@@ -0,0 +1,9 @@
+/** Light tap — a button press or a stepper step. */
+export declare function tapFeedback(): void;
+/** Selection tick — picking an option or flipping a switch. */
+export declare function selectFeedback(): void;
+/** An action that succeeded (saved, drawn, sent…). */
+export declare function successFeedback(): void;
+/** An action that failed. */
+export declare function errorFeedback(): void;
+//# sourceMappingURL=haptics.d.ts.map

package/dist/utils/helpers/haptics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"haptics.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers/haptics.ts"],"names":[],"mappings":"AAMA,oDAAoD;AACpD,wBAAgB,WAAW,IAAI,IAAI,CAIlC;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AAED,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,IAAI,CAMtC;AAED,6BAA6B;AAC7B,wBAAgB,aAAa,IAAI,IAAI,CAMpC"}

package/dist/utils/helpers/haptics.js

@@ -0,0 +1,28 @@
+import * as Haptics from "expo-haptics";
+// Semantic aliases around expo-haptics. Every call is fire-and-forget: a
+// failed vibration (web, no motor, haptics off) must never fail the action it
+// accompanies.
+/** Light tap — a button press or a stepper step. */
+export function tapFeedback() {
+    Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light).catch(() => {
+        /* best effort */
+    });
+}
+/** Selection tick — picking an option or flipping a switch. */
+export function selectFeedback() {
+    Haptics.selectionAsync().catch(() => {
+        /* best effort */
+    });
+}
+/** An action that succeeded (saved, drawn, sent…). */
+export function successFeedback() {
+    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success).catch(() => {
+        /* best effort */
+    });
+}
+/** An action that failed. */
+export function errorFeedback() {
+    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error).catch(() => {
+        /* best effort */
+    });
+}

package/dist/utils/helpers/index.d.ts

@@ -1,3 +1,8 @@
 export * from "./confirmDestructive.js";
+export * from "./haptics.js";
+export * from "./isNativeModuleAvailable.js";
 export * from "./mergeSlotStyles.js";
+export * from "./shareFile.js";
+export * from "./shareTextFile.js";
+export * from "./shareViewAsImage.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/helpers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC"}

package/dist/utils/helpers/index.js

@@ -1,2 +1,7 @@
 export * from "./confirmDestructive.js";
+export * from "./haptics.js";
+export * from "./isNativeModuleAvailable.js";
 export * from "./mergeSlotStyles.js";
+export * from "./shareFile.js";
+export * from "./shareTextFile.js";
+export * from "./shareViewAsImage.js";

package/dist/utils/helpers/isNativeModuleAvailable.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether the native module `name` is compiled into this binary (new or old
+ * architecture). Check it before loading a library that requires its native
+ * module on import: on a binary built without it (an older dev build),
+ * importing it anyway crashes the whole screen instead of disabling the one
+ * feature that needs it.
+ *
+ * @example
+ * if (isNativeModuleAvailable("RNViewShot")) showShareAsImageButton();
+ */
+export declare function isNativeModuleAvailable(name: string): boolean;
+//# sourceMappingURL=isNativeModuleAvailable.d.ts.map

package/dist/utils/helpers/isNativeModuleAvailable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isNativeModuleAvailable.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers/isNativeModuleAvailable.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7D"}