diff --git a/docs/frontend/gallery-view.md b/docs/frontend/gallery-view.md new file mode 100644 index 000000000..c4953130d --- /dev/null +++ b/docs/frontend/gallery-view.md @@ -0,0 +1,35 @@ +# Gallery View + +The gallery view is the main way users browse and interact with their photos in PictoPy. It presents media in a responsive grid, organized by date, with filtering and AI-backed organization. + +## Overview + +The main gallery shows photos and videos in a grid layout. Images are grouped by date, and users can filter by tags, favourites, and other criteria. The gallery connects to the [state management](state-management.md) layer for images and folders, and uses shared [UI components](ui-components.md) for layout and controls. + +## Layout and Behavior + +- **Grid layout** – Media is displayed in a responsive grid that adapts to window size. +- **Date grouping** – Items are organized chronologically (by capture or file date) for quick scanning. +- **Filtering** – Users can filter by tagged status, favourites, and other attributes exposed in the UI. +- **Thumbnails** – Each item is shown as a thumbnail with optional overlays (e.g. favourite icon, AI tags). + +## Key Components + +The gallery experience is built from several frontend components: + +- **ChronologicalGallery** – Renders the date-grouped grid of media. +- **ImageCard** – Renders a single thumbnail, metadata hints, and interaction targets (e.g. select, favourite). +- **MediaView** / **ImageViewer** – Full-size view and navigation when a photo or video is opened. +- **MediaThumbnails** – Thumbnail strip or grid used in the lightbox/viewer. +- **MediaInfoPanel** – Shows metadata, tags, and location for the currently viewed item. +- **MediaViewControls**, **ZoomControls**, **NavigationButtons** – Control zoom, next/previous, and other viewer actions. + +## Screenshots + +For visual examples of the main gallery, AI tagging, and related screens, see [Screenshots](screenshots.md). + +## Related Documentation + +- [State Management](state-management.md) – How images and folders are stored and updated in the Redux store. +- [Screenshots](screenshots.md) – Screenshots of the main gallery and other views. +- [UI Components](ui-components.md) – Shared components used in the gallery and across the app. diff --git a/docs/frontend/ui-components.md b/docs/frontend/ui-components.md new file mode 100644 index 000000000..0aa80ae6c --- /dev/null +++ b/docs/frontend/ui-components.md @@ -0,0 +1,88 @@ +# UI Components + +PictoPy’s frontend uses a mix of shared primitives (based on ShadCN) and app-specific components. This page gives an overview of both so you can find and reuse the right parts when building or changing the UI. + +## Overview + +- **Primitives** live under `components/ui/` and provide buttons, inputs, dialogs, and other low-level building blocks. +- **Feature components** implement gallery, onboarding, navigation, and media behaviour and often use these primitives. + +## ShadCN-style primitives (`components/ui/`) + +These are the base components used across the app: + +| Component | Role | +|----------------|--------------------------------------------------| +| `button` | Buttons with variants (default, outline, ghost) | +| `card` | Card container with header, content, footer | +| `dialog` | Modal dialogs | +| `input` | Text inputs | +| `label` | Form labels | +| `textarea` | Multi-line text input | +| `badge` | Tags and status badges | +| `alert` | Inline alerts and messages | +| `avatar` | User or entity avatars | +| `dropdown-menu`| Dropdown menus | +| `scroll-area` | Custom scrollable areas | +| `sidebar` | App sidebar layout | +| `sheet` | Slide-out panels | +| `separator` | Visual dividers | +| `switch` | Toggle switches | +| `radio-group` | Radio button groups | +| `pagination` | Pagination controls | +| `progress` | Progress bars | +| `skeleton` | Loading skeletons | +| `tooltip` | Hover tooltips | +| `aspect-ratio` | Fixed aspect-ratio wrapper | + +App-specific UI pieces in the same area: + +- **404** – Not-found page layout +- **ErrorPage** – Full-page error view +- **LoadingScreen** – App loading screen +- **Icons** – Shared icon set +- **PaginationControls** – Pagination tuned for the gallery + +## Feature components + +These implement specific features and often use the primitives above: + +### Media and gallery + +- **Media/** – `ChronologicalGallery`, `ImageCard`, `ImageViewer`, `MediaView`, `MediaThumbnails`, `MediaInfoPanel`, `MediaViewControls`, `ZoomControls`, `NavigationButtons`, `ImageTags` +- **FaceCollections** – Face clusters and naming UI + +### Navigation and layout + +- **Navigation/Navbar** – Top app bar +- **Navigation/Sidebar** – App sidebar (e.g. `AppSidebar`) + +### Onboarding and settings + +- **OnboardingSteps/** – Steps, folder setup, avatar choice, theme selection, server check, etc. +- **account-settings** – User account and preference UI + +### Dialogs and feedback + +- **Dialog/** – `InfoDialog`, `FaceSearchDialog` +- **Loader/** – `GlobalLoader` +- **EmptyStates/** – `EmptyGalleryState`, `EmptyAITaggingState` + +### Other + +- **FolderPicker/** – Folder selection and related dialogs (e.g. `DeleteImageDialog`) +- **ThemeToggle** – Light/dark theme switch +- **Timeline/** – `TimelineScrollbar` +- **Updater/** – `UpdateDialog` +- **VideoPlayer/** – `NetflixStylePlayer` +- **WebCam/** – `WebCamComponent` + +## Styling + +UI components are styled with **Tailwind CSS**. Shared look and behaviour (including themes) are kept consistent via Tailwind classes and the design tokens used by the ShadCN-based components. + +## Related documentation + +- [Gallery View](gallery-view.md) – How the main gallery is built from these components +- [State Management](state-management.md) – How components connect to Redux +- [Screenshots](screenshots.md) – Screenshots of the app using these components diff --git a/mkdocs.yml b/mkdocs.yml index 70778130f..6f29e8e8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,8 @@ nav: - Python Backend Image Processing: backend/backend_python/image-processing.md - Rust Backend API: backend/backend_rust/api.md - Frontend: + - UI Components: frontend/ui-components.md + - Gallery View: frontend/gallery-view.md - State Management: frontend/state-management.md - Screenshots: frontend/screenshots.md