Contacts

Contacts is an Address Book-style app for ryOS that lets you manage contacts with groups, vCard import, custom photos, and cloud sync. Ryo can list, create, update, and search contacts via chat and Telegram.

Overview

Contacts provides an Address Book-style interface for managing contacts in ryOS. It supports creating and editing contacts with names, phones, emails, addresses, URLs, birthdays, nicknames, and notes. Contacts can be organized with smart groups (All, Imported, Telegram, Work, Birthdays), searched with a built-in search bar, and imported from vCard (.vcf) files. Custom photos can be added via a picture picker (preset avatars or custom upload). The "My Card" feature pins your own contact at the top. Contacts sync to the cloud when enabled in Control Panels, and Ryo integrates with the address book via AI tools in Chats. The app adapts to all four OS themes (System 7, macOS Aqua, Windows XP, Windows 98) and offers a responsive mobile layout with a collapsible group sidebar and Card Only view.

Features

Contact CRUD: Create, edit, and delete contacts with first/last name, organization, phones, emails, addresses, URLs, birthday, nickname, and notes

Groups: Filter by All, Imported (vCard source), Telegram (contacts with Telegram data), Work (organization/title), and Birthdays
vCard Import: Import .vcf/.vcard files from the File menu; supports merge with existing contacts and photo resizing
Custom Photos: UserPicturePicker with preset avatars or custom image upload; tap avatar on the card to change
Cloud Sync: Sync contacts to Redis via Control Panels > Auto Sync
Search: Inline search bar filters contacts by name, email, phone, organization, and notes
Spotlight Search: Contacts appear in Spotlight search results
AI Tool Integration: Ryo can list, create, update, and delete synced contacts in Chats and Telegram
"Mark as Mine": Pin your own contact at the top with a "My Card" badge (Edit > Mark as Mine)
Tappable Links: Phone, email, and URL fields are clickable (tel:, mailto:, https:)
Responsive Layout: Mobile layout (< 640px) shows compact list and card panels; group sidebar can be toggled; Card Only view hides list
Theme Support: Adapts to System 7, macOS Aqua (brushed metal), Windows XP, and Windows 98
Multi-value Fields: Phones, emails, addresses, and URLs support multiple values (newline or comma separated)

User Guide

Getting Started

Launch Contacts from the application launcher. The window opens with the group sidebar, contact list, and card panel. Select a contact from the list to view or edit its details. Use the + button or File > New Contact to create a contact (editing opens automatically).

Key Actions

Add Contact: Click + or File > New Contact
Edit Contact: Select a contact and click Edit, then Done when finished
Delete Contact: While editing, click Delete at the bottom of the card, or Edit > Delete Contact
Import vCards: File > Import vCard to select a .vcf file
Sync Contacts: File > Sync Contacts (or enable Auto Sync in Control Panels)
Mark as Mine: Select your contact and choose Edit > Mark as Mine
Change Photo: Select a contact and click its avatar to open the picture picker
Search: Type in the search bar to filter contacts
Switch Groups: Click a group in the sidebar (All, Imported, Telegram, Work, Birthdays)

Tips & Shortcuts

Toggle Groups and Card Only using the toolbar buttons to customize the layout
Contacts auto-save as you edit—no manual save needed
Ask Ryo in Chats to create or update contacts; synced contacts are available to the AI
Enable Contacts sync in Control Panels to keep data in the cloud

Technical Details

Window Configuration

Default size: 820×560px
Minimum size: 360×420px

Component Architecture

src/apps/contacts/components/ContactsAppComponent.tsx — Main app with group/list/card panels, edit mode, and toolbar
src/apps/contacts/components/ContactsMenuBar.tsx — Menu bar with File, Edit, Help
src/apps/contacts/components/UserPicturePicker.tsx — Dialog for selecting contact avatar (presets or custom image)

Hooks & Utilities

src/apps/contacts/hooks/useContactsLogic.ts — Search, groups, filtering, CRUD handlers, vCard import
src/utils/contacts.ts — Contact model, vCard parsing (parseVCardText), search (contactMatchesQuery), sorting (sortContacts), merge logic

State Management

useContactsStore (src/stores/useContactsStore.ts) — Zustand store with localStorage persistence (contacts-storage). Holds contacts, selectedContactId, myContactId, lastRemoteSyncAt. Exposes addContact, updateContact, deleteContact, importContacts, replaceContactsFromSync. Seed contacts via seedDefaultContacts. Cloud sync replaces contacts via replaceContactsFromSync.

Related Apps

Calendar: Birthdays and events can reference contact data

Chats: Ryo uses the contactsControl AI tool to list, create, update, and delete contacts
Dashboard: Can display contact-related widgets
Control Panels: Enable Contacts sync under Auto Sync for cloud persistence