From 691ee98792c38fa11bd15adb26e43e60d20d6ac3 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:24:01 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`dev`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @fortune710. * https://github.com/fortune710/keepsafe/pull/20#issuecomment-3719117219 The following files were modified: * `frontend/app/capture/details.tsx` * `frontend/components/capture/canvas/text-canvas-item.tsx` * `frontend/components/capture/editor-popover.tsx` * `frontend/components/capture/editor/location-tab.tsx` * `frontend/components/capture/editor/music-tab.tsx` * `frontend/components/capture/editor/text-tab.tsx` * `frontend/components/capture/entry-attachment-list.tsx` * `frontend/components/capture/music/audio-preview-popover.tsx` * `frontend/components/capture/music/music-list-item.tsx` * `frontend/hooks/use-device-location.ts` * `frontend/hooks/use-media-canvas.ts` * `frontend/hooks/use-places-search.ts` --- frontend/app/capture/details.tsx | 12 +++++++++++- .../capture/canvas/text-canvas-item.tsx | 13 +++++++++++++ frontend/components/capture/editor-popover.tsx | 17 ++++++++++++++++- .../components/capture/editor/location-tab.tsx | 9 ++++++++- .../components/capture/editor/music-tab.tsx | 5 +++++ .../components/capture/editor/text-tab.tsx | 18 +++++++++++++++++- .../capture/entry-attachment-list.tsx | 10 +++++++++- .../capture/music/audio-preview-popover.tsx | 12 +++++++++++- .../capture/music/music-list-item.tsx | 7 +++++++ frontend/hooks/use-device-location.ts | 13 +++++++++++++ frontend/hooks/use-media-canvas.ts | 14 ++++++++++++++ frontend/hooks/use-places-search.ts | 9 ++++++++- 12 files changed, 132 insertions(+), 7 deletions(-) diff --git a/frontend/app/capture/details.tsx b/frontend/app/capture/details.tsx index 3f0c807..73e82bb 100644 --- a/frontend/app/capture/details.tsx +++ b/frontend/app/capture/details.tsx @@ -37,6 +37,16 @@ interface Friend { username: string; } +/** + * Render the details screen for reviewing a captured media item, editing attachments, + * configuring sharing options, and saving the entry. + * + * This component builds a MediaCapture from route params, manages attachment editing + * (including in-editor live text editing with pending item handling), sharing state + * (private, everyone, or selected friends), optimistic entry creation, and the save flow. + * + * @returns The Details screen UI for adding details to a capture, managing attachments and privacy, and submitting the entry. + */ export default function DetailsScreen() { const params = useLocalSearchParams(); const { captureId, type, uri, duration } = params; @@ -591,4 +601,4 @@ const styles = StyleSheet.create({ fontSize: 18, fontWeight: '600', }, -}); +}); \ No newline at end of file diff --git a/frontend/components/capture/canvas/text-canvas-item.tsx b/frontend/components/capture/canvas/text-canvas-item.tsx index 4a25b31..4428fdd 100644 --- a/frontend/components/capture/canvas/text-canvas-item.tsx +++ b/frontend/components/capture/canvas/text-canvas-item.tsx @@ -5,6 +5,19 @@ interface TextCanvasItemProps { textStyle?: { color: string; fontFamily?: string; backgroundColor?: string } } +/** + * Renders a rounded text "badge" using the provided text and optional styling. + * + * Applies `textStyle.backgroundColor` to the container (defaults to `#000000` if not provided) + * and applies `textStyle.color` and `textStyle.fontFamily` to the text. + * + * @param text - The string to display; if falsy, the component renders `null`. + * @param textStyle - Optional visual overrides. Recognized properties: + * - `backgroundColor`: container background color + * - `color`: text color + * - `fontFamily`: text font family + * @returns A React element containing the styled text badge, or `null` when `text` is falsy. + */ export function TextCanvasItem({ text, textStyle }: TextCanvasItemProps) { if (!text) return null; diff --git a/frontend/components/capture/editor-popover.tsx b/frontend/components/capture/editor-popover.tsx index 41297cc..f27ff5f 100644 --- a/frontend/components/capture/editor-popover.tsx +++ b/frontend/components/capture/editor-popover.tsx @@ -38,6 +38,21 @@ interface EditorPopoverProps { initialText?: string; } +/** + * Render an editor popover that lets users add text, stickers, music, or a location to a media canvas. + * + * @param isVisible - Whether the popover is currently visible + * @param onClose - Callback invoked when the popover is dismissed; receives the current text input (if any) + * @param addText - Adds a text item with style `{ color, fontFamily?, backgroundColor? }` + * @param addSticker - Adds a sticker given its URI + * @param addMusic - Adds a music tag + * @param addLocation - Adds a location string + * @param defaultTab - Optional initial active tab (`"text" | "sticker" | "music" | "location"`) + * @param onTextChange - Optional callback invoked as the text input changes + * @param onStyleChange - Optional callback invoked when text style (color, fontFamily, backgroundColor) changes + * @param initialText - Optional initial value for the text input + * @returns The popover UI element when visible, or `null` when hidden + */ export default function EditorPopover({ isVisible, onClose, @@ -275,4 +290,4 @@ const styles = StyleSheet.create({ alignItems: "center", justifyContent: "center", }, -}); +}); \ No newline at end of file diff --git a/frontend/components/capture/editor/location-tab.tsx b/frontend/components/capture/editor/location-tab.tsx index ea5b926..5140192 100644 --- a/frontend/components/capture/editor/location-tab.tsx +++ b/frontend/components/capture/editor/location-tab.tsx @@ -19,6 +19,14 @@ interface LocationSearchResult { isCurrentLocation?: boolean; } +/** + * Renders a location search interface that lists nearby places and search results and lets the user pick a location. + * + * Displays an input for typing a query, shows a combined list containing an optional "Current" location entry and place results, indicates loading/empty states, and invokes a callback when a location is selected. + * + * @param onSelectLocation - Callback invoked with the selected location string (address) when the user chooses a location + * @returns The LocationTab component UI for searching and selecting a location + */ export default function LocationTab({ onSelectLocation }: LocationTabProps) { const [searchQuery, setSearchQuery] = useState(""); const debouncedQuery = useDebounce(searchQuery, 500); @@ -280,4 +288,3 @@ const styles = StyleSheet.create({ fontSize: 16, }, }); - diff --git a/frontend/components/capture/editor/music-tab.tsx b/frontend/components/capture/editor/music-tab.tsx index c82f4ae..de3bd13 100644 --- a/frontend/components/capture/editor/music-tab.tsx +++ b/frontend/components/capture/editor/music-tab.tsx @@ -50,6 +50,11 @@ export default function MusicTab({ isLoading, musicQuery, onMusicQueryChange, mu ) } +/** + * Renders the empty-state view shown when no music results are available. + * + * @returns The empty-state React element containing a music icon and the prompt "Start searching for music". + */ function EmptyComponent() { return ( diff --git a/frontend/components/capture/editor/text-tab.tsx b/frontend/components/capture/editor/text-tab.tsx index 0d74e04..4b59f9a 100644 --- a/frontend/components/capture/editor/text-tab.tsx +++ b/frontend/components/capture/editor/text-tab.tsx @@ -28,6 +28,22 @@ const POPULAR_COLORS = [ "#FF1493", "#00CED1", "#32CD32", "#FF4500", "#DA70D6", ]; +/** + * Renders a multi-tab text editor panel for editing text, text color, background color, and font. + * + * Provides an internal tab bar with: a multiline text input (auto-focused when active), a text color picker + * (preset palette plus optional custom ColorSlider), a background color picker (same behavior), and a font selector. + * + * @param textInput - Current text value shown in the editor + * @param onTextChange - Called with the new text when the user edits the text input + * @param selectedColor - Currently selected text color (hex string) + * @param onColorChange - Called with a hex color when the text color is changed + * @param selectedFont - Currently selected font name + * @param onFontChange - Called with the font name when a font is selected + * @param selectedBackgroundColor - Currently selected background color (hex string); defaults to `#000000` + * @param onBackgroundColorChange - Optional callback called with a hex color when the background color is changed + * @returns A React element containing the internal tab bar and the active tab's content + */ export default function TextTab({ textInput, onTextChange, @@ -379,4 +395,4 @@ const styles = StyleSheet.create({ fontFamily: 'monospace', textAlign: 'center', }, -}) +}) \ No newline at end of file diff --git a/frontend/components/capture/entry-attachment-list.tsx b/frontend/components/capture/entry-attachment-list.tsx index dae5007..ffecdee 100644 --- a/frontend/components/capture/entry-attachment-list.tsx +++ b/frontend/components/capture/entry-attachment-list.tsx @@ -13,6 +13,15 @@ const attachmentTypes: { type: MediaCanvasItemType; icon: React.ComponentType @@ -86,4 +95,3 @@ const styles = StyleSheet.create({ textAlign: 'center', }, }); - diff --git a/frontend/components/capture/music/audio-preview-popover.tsx b/frontend/components/capture/music/audio-preview-popover.tsx index 30f30f4..ac2ddf4 100644 --- a/frontend/components/capture/music/audio-preview-popover.tsx +++ b/frontend/components/capture/music/audio-preview-popover.tsx @@ -22,6 +22,16 @@ interface MusicPopoverProps { music: MusicTag; } +/** + * Render a sliding "Now Playing" popover that previews a music item and its metadata. + * + * Renders an overlay with a backdrop and an animated popover containing an AudioPreview, cover image, title, artist, and a Close action. The popover mounts only when `isVisible` is true; the overlay remains while exit animation runs. + * + * @param isVisible - Whether the popover is currently visible + * @param onClose - Callback invoked when the backdrop or Close button is pressed + * @param music - The music item to preview (expects `MusicTag` shape with `preview`, `cover`, `title`, and `artist`) + * @returns The popover JSX element, or `null` when neither visible nor provided with a music item + */ export default function AudioPreviewPopover({ isVisible, onClose, music }: MusicPopoverProps) { // Don't return null - let the exit animation play @@ -177,4 +187,4 @@ const styles = StyleSheet.create({ fontWeight: '600', textAlign: 'center', }, -}); +}); \ No newline at end of file diff --git a/frontend/components/capture/music/music-list-item.tsx b/frontend/components/capture/music/music-list-item.tsx index 0c45f3c..de32226 100644 --- a/frontend/components/capture/music/music-list-item.tsx +++ b/frontend/components/capture/music/music-list-item.tsx @@ -10,6 +10,13 @@ interface MusicListItemProps { onPress?: (music: MusicTag) => void; } +/** + * Render a touchable list item showing a music cover, title, artist, and an audio preview control. + * + * @param music - The music item to display (cover URI, title, artist, and preview source) + * @param onPress - Optional callback invoked with `music` when the item is pressed + * @returns The rendered list item element for the given `music` + */ export function MusicListItem({ music, onPress }: MusicListItemProps) { const handleMusicSelection = () => { onPress && onPress(music); diff --git a/frontend/hooks/use-device-location.ts b/frontend/hooks/use-device-location.ts index 3115df4..b6407cd 100644 --- a/frontend/hooks/use-device-location.ts +++ b/frontend/hooks/use-device-location.ts @@ -35,6 +35,19 @@ interface UseDeviceLocationResult { clearLocation: () => void; } +/** + * Exposes the device's current location and a list of representative places within the device's region. + * + * Provides current device location (when permissions are granted), a cached/throttled list of places derived from the device's region, loading states for both queries, any error message, and a function to clear the cached location and places. + * + * @returns An object with the following properties: + * - `location` — The resolved `LocationData` for the device, or `null` if permissions were not granted or location is unavailable. + * - `placesInState` — An array of `PlaceResult` representing places found within the device's region (may be empty). + * - `isLoading` — `true` while the device location query is loading or fetching, otherwise `false`. + * - `isLoadingPlaces` — `true` while the places-in-state query is loading, otherwise `false`. + * - `error` — A user-facing error message string when the location query fails, or `null` if there is no error. + * - `clearLocation` — A function that clears the cached device location and the cached places-in-state. + */ export function useDeviceLocation(): UseDeviceLocationResult { const queryClient = useQueryClient(); diff --git a/frontend/hooks/use-media-canvas.ts b/frontend/hooks/use-media-canvas.ts index 829d9f1..08033d9 100644 --- a/frontend/hooks/use-media-canvas.ts +++ b/frontend/hooks/use-media-canvas.ts @@ -3,6 +3,20 @@ import { useRef, useState } from "react"; import { Platform, View } from "react-native"; import ViewShot, { captureRef } from "react-native-view-shot"; +/** + * Manage a collection of media canvas items and provide utilities to capture the canvas as an image. + * + * @returns An object exposing: + * - `viewShotRef`: a ref to the ViewShot instance (or `null`) for capturing the rendered view. + * - `items`: the current array of `MediaCanvasItem`. + * - `addText(text, style)`: adds a text item and returns the generated numeric id. + * - `addSticker(sticker)`: adds a sticker item. + * - `addMusic(music)`: adds a music item (`MusicTag`). + * - `addLocation(location)`: adds a location item. + * - `removeElement(id)`: removes the item with the given id. + * - `updateTextItem(id, text, style)`: updates the text and style of an existing text item. + * - `saveImage()`: captures the view and returns the captured file URI prefixed with `file://` on success, or `null` on failure. + */ export function useMediaCanvas() { const [items, setItems] = useState>([]); diff --git a/frontend/hooks/use-places-search.ts b/frontend/hooks/use-places-search.ts index 3a6cdab..3cc07bb 100644 --- a/frontend/hooks/use-places-search.ts +++ b/frontend/hooks/use-places-search.ts @@ -1,6 +1,14 @@ import { useQuery } from '@tanstack/react-query'; import { PlacesSearchService, PlacesSearchCoordinates } from '@/services/places-search-service'; +/** + * Searches for places matching a search term, optionally biased by coordinates. + * + * @param query - The search term to look up. + * @param options - Optional settings for the search. + * @param options.coordinates - Latitude and longitude used to bias the search results. + * @returns An object containing `places` (search results; defaults to an empty array), `isLoading` (whether the query is in progress), and `error` (any error encountered). + */ export function usePlacesSearch( query: string, options: { coordinates?: PlacesSearchCoordinates } = {} @@ -23,4 +31,3 @@ export function usePlacesSearch( error, }; } -