@togo-framework/ui-desktop 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 togo-framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

package/README.md

@@ -0,0 +1,18 @@
+<!-- togo-header -->
+# @togo-framework/ui-desktop
+
+OS-like desktop shell on top of the `os` plugin: dock, window manager,
+spotlight, launchpad, notification center, and a lock/login screen. Part of
+the togo UI kit.
+
+```bash
+npm install @togo-framework/ui-desktop
+```
+
+```tsx
+import { DesktopShell, WindowManagerProvider } from "@togo-framework/ui-desktop";
+```
+
+Requires `@togo-framework/ui-core` and `@togo-framework/ui-auth` (the login
+screen reuses the shared LockScreen/PasswordLockScreen components).
+<!-- togo-sponsors -->

package/dist/index.d.ts

@@ -0,0 +1,467 @@
+import * as React from 'react';
+import { AuthClient, LockScreenUser, PasswordLockScreenUser, UnlockCredentials } from '@togo-framework/ui-auth';
+
+interface OSNotification {
+    id: string;
+    type: string;
+    title: string;
+    body?: string;
+    action_url?: string;
+    read: boolean;
+    created_at: string;
+}
+interface NotificationBellProps {
+    notifications: OSNotification[];
+    unreadCount: number;
+    onMarkRead: (id: string) => void;
+    onMarkAllRead: () => void;
+    /** Called when the popover is opened — the consumer fetches fresh data. */
+    onFetch?: () => void;
+    onNavigate?: (url: string) => void;
+    className?: string;
+}
+declare function NotificationBell({ notifications, unreadCount, onMarkRead, onMarkAllRead, onFetch, onNavigate, className, }: NotificationBellProps): React.JSX.Element;
+declare namespace NotificationBell {
+    var displayName: string;
+}
+
+interface TogoMenuProps {
+    /** Logo glyph (defaults to the togo layers mark). */
+    logo?: React.ReactNode;
+    label?: string;
+    onAbout?: () => void;
+    onSettings?: () => void;
+    onSleep?: () => void;
+    onRestart?: () => void;
+    onShutDown?: () => void;
+    onLogout?: () => void;
+}
+declare function TogoMenu({ logo, label, onAbout, onSettings, onSleep, onRestart, onShutDown, onLogout, }: TogoMenuProps): React.JSX.Element;
+declare namespace TogoMenu {
+    var displayName: string;
+}
+
+type WeatherCondition = "clear" | "cloudy" | "rain" | "snow" | "storm" | "fog" | "partly";
+interface WeatherData {
+    /** Temperature already formatted's numeric value (°). */
+    temp: number;
+    condition: WeatherCondition;
+    location?: string;
+    /** Unit label, default "°". */
+    unit?: string;
+}
+interface WeatherWidgetProps {
+    weather?: WeatherData | null;
+    onClick?: () => void;
+    className?: string;
+}
+declare function WeatherWidget({ weather, onClick, className }: WeatherWidgetProps): React.JSX.Element | null;
+declare namespace WeatherWidget {
+    var displayName: string;
+}
+
+interface TopBarProps {
+    me: {
+        email: string;
+    } | null;
+    onLogout: () => void;
+    onProfile?: () => void;
+    menu?: Omit<TogoMenuProps, "onLogout"> & {
+        enabled?: boolean;
+    };
+    notifications?: OSNotification[];
+    unreadCount?: number;
+    onMarkRead?: (id: string) => void;
+    onMarkAllRead?: () => void;
+    onFetchNotifications?: () => void;
+    onNavigate?: (url: string) => void;
+    /** Clicking the clock (and, if provided, the bell) opens the notification center. */
+    onOpenNotifications?: () => void;
+    onOpenSpotlight?: () => void;
+    weather?: WeatherData | null;
+    onWeatherClick?: () => void;
+    className?: string;
+}
+declare function TopBar({ me, onLogout, onProfile, menu, onOpenNotifications, onOpenSpotlight, weather, onWeatherClick, className, }: TopBarProps): React.JSX.Element;
+declare namespace TopBar {
+    var displayName: string;
+}
+
+type DesktopContextAction = "change-wallpaper" | "personalize" | "refresh";
+interface DesktopContextMenuProps {
+    onAction: (action: DesktopContextAction) => void;
+    children: React.ReactNode;
+    className?: string;
+}
+declare function DesktopContextMenu({ onAction, children, className }: DesktopContextMenuProps): React.JSX.Element;
+declare namespace DesktopContextMenu {
+    var displayName: string;
+}
+
+interface OSAppWindow {
+    width: number;
+    height: number;
+    resizable: boolean;
+}
+interface OSApp {
+    slug: string;
+    name: string;
+    icon: string;
+    color: string;
+    category: string;
+    window: OSAppWindow;
+    enabled: boolean;
+}
+interface UseOSAppsResult {
+    apps: OSApp[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+}
+declare function useOSApps(basePath?: string): UseOSAppsResult;
+
+interface DesktopPrefs {
+    theme: string;
+    accent: string;
+    wallpaper: string;
+    lock_wallpaper: string;
+    dock_pinned: string[];
+    desktop_hidden: string[];
+    icon_positions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+}
+interface UseOSSessionResult {
+    prefs: DesktopPrefs;
+    setPrefs: (prefs: DesktopPrefs | ((prev: DesktopPrefs) => DesktopPrefs)) => void;
+    /** Persists the current `prefs` (or an explicit override) via PUT. */
+    save: (next?: DesktopPrefs) => Promise<void>;
+    loading: boolean;
+    error: string | null;
+}
+declare function useOSSession(basePath?: string): UseOSSessionResult;
+
+interface DesktopShellProps {
+    /** Current desktop preferences (wallpaper, dock_pinned, ...) — e.g. from useOSSession(). */
+    prefs: DesktopPrefs;
+    /** Installed apps — e.g. from useOSApps(). */
+    apps: OSApp[];
+    /** Renders window content for a given app slug. */
+    renderApp: (app: OSApp) => React.ReactNode;
+    /** Top-bar props (me / logout / weather / menu callbacks / notifications data). */
+    topBar: Omit<TopBarProps, "className" | "onOpenSpotlight" | "onOpenNotifications">;
+    /** Notifications for the sideover (same list the bell uses). */
+    notifications?: OSNotification[];
+    unreadCount?: number;
+    onMarkRead?: (id: string) => void;
+    onMarkAllRead?: () => void;
+    onNavigate?: (url: string) => void;
+    onContextAction?: (action: DesktopContextAction) => void;
+    /** Opens the Trash (dock). */
+    onTrash?: () => void;
+    /** Saved desktop-icon positions (DesktopPrefs.icon_positions). */
+    iconPositions?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Persist a desktop-icon position after a drag. */
+    onIconMove?: (slug: string, pos: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Slugs hidden from the desktop (DesktopPrefs.desktop_hidden). */
+    desktopHidden?: string[];
+    /** Remove an app icon from the desktop. */
+    onRemoveDesktopIcon?: (slug: string) => void;
+    /** Add an app icon back to the desktop (from Launchpad). */
+    onAddDesktopIcon?: (slug: string) => void;
+    /** Pin an app to the dock (from Launchpad). */
+    onPinDock?: (slug: string) => void;
+    /** Unpin an app from the dock (dock/Launchpad context menu). */
+    onUnpinDock?: (slug: string) => void;
+    /**
+     * Called once the shell is mounted, with an imperative API so the host page
+     * can open app windows from outside the shell (e.g. a top-bar shortcut).
+     */
+    onReady?: (api: DesktopApi) => void;
+    className?: string;
+}
+/** Imperative handle exposed via DesktopShellProps.onReady. */
+interface DesktopApi {
+    /**
+     * Open (or restore/focus) a registered app by slug, optionally deep-linking to
+     * a section inside it (e.g. open("prefs", "wallpaper") jumps Settings straight
+     * to the Wallpaper pane). The app reads the target via useWindowSection().
+     */
+    open: (slug: string, section?: string) => void;
+    /** Open (or restore/focus) an arbitrary window not backed by an installed app. */
+    openWindow: (opts: {
+        slug: string;
+        title: string;
+        icon?: string;
+        width?: number;
+        height?: number;
+        content: React.ReactNode;
+        section?: string;
+    }) => void;
+}
+declare function DesktopShell({ prefs, apps, renderApp, topBar, notifications, unreadCount, onMarkRead, onMarkAllRead, onNavigate, onContextAction, onTrash, onReady, iconPositions, onIconMove, desktopHidden, onRemoveDesktopIcon, onAddDesktopIcon, onPinDock, onUnpinDock, className, }: DesktopShellProps): React.JSX.Element;
+declare namespace DesktopShell {
+    var displayName: string;
+}
+
+interface DockProps {
+    /** All installed apps (used to resolve name/icon/color for pinned slugs). */
+    apps: OSApp[];
+    /** Slugs to show, in order (pinned, or all installed apps as a fallback). */
+    pinned: string[];
+    /** Slugs of currently-open windows — shown with an "open" indicator dot. */
+    openSlugs?: string[];
+    onLaunch: (slug: string) => void;
+    /** Right-click → Quit on a running app icon. */
+    onCloseApp?: (slug: string) => void;
+    /** Right-click → Remove from Dock (unpin). */
+    onUnpin?: (slug: string) => void;
+    /** Opens the Launchpad / app directory (leading icon). */
+    onLaunchpad?: () => void;
+    /** Opens the Trash (trailing icon). */
+    onTrash?: () => void;
+    className?: string;
+}
+declare function Dock({ apps, pinned, openSlugs, onLaunch, onCloseApp, onUnpin, onLaunchpad, onTrash, className }: DockProps): React.JSX.Element;
+declare namespace Dock {
+    var displayName: string;
+}
+
+interface IconPos {
+    x: number;
+    y: number;
+}
+interface DesktopIconGridProps {
+    apps: OSApp[];
+    onOpen: (slug: string) => void;
+    /** Saved per-slug positions (DesktopPrefs.icon_positions). */
+    positions?: Record<string, IconPos>;
+    /** Called when an icon is dragged to a new position. Enables drag mode. */
+    onMove?: (slug: string, pos: IconPos) => void;
+    /** Slugs hidden from the desktop (DesktopPrefs.desktop_hidden). */
+    hidden?: string[];
+    /** Right-click → Remove from Desktop. */
+    onRemove?: (slug: string) => void;
+    className?: string;
+}
+declare function DesktopIconGrid({ apps, onOpen, positions, onMove, hidden, onRemove, className }: DesktopIconGridProps): React.JSX.Element;
+declare namespace DesktopIconGrid {
+    var displayName: string;
+}
+
+interface DesktopIconProps {
+    app: OSApp;
+    onOpen: (slug: string) => void;
+    selected?: boolean;
+    onSelect?: (slug: string) => void;
+    /** Open on a single click/tap (mobile-friendly) instead of double-click. */
+    tapToOpen?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function DesktopIcon({ app, onOpen, selected, onSelect, tapToOpen, className, style }: DesktopIconProps): React.JSX.Element;
+declare namespace DesktopIcon {
+    var displayName: string;
+}
+
+interface WindowRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+declare function clampWindowRect(r: WindowRect): WindowRect;
+interface WindowProps {
+    title: string;
+    icon?: string;
+    rect: WindowRect;
+    onRectChange: (rect: WindowRect) => void;
+    resizable?: boolean;
+    minimized?: boolean;
+    zIndex?: number;
+    onClose: () => void;
+    onMinimize?: () => void;
+    onMaximizeToggle?: () => void;
+    maximized?: boolean;
+    onFocus?: () => void;
+    className?: string;
+    children?: React.ReactNode;
+}
+declare function Window({ title, icon, rect, onRectChange, resizable, minimized, zIndex, onClose, onMinimize, onMaximizeToggle, maximized, onFocus, className, children, }: WindowProps): React.JSX.Element;
+declare namespace Window {
+    var displayName: string;
+}
+/** Centered loading spinner used as the window content fallback. */
+declare function WindowSpinner(): React.JSX.Element;
+
+interface OpenWindowOptions {
+    title: string;
+    icon?: string;
+    resizable?: boolean;
+    width?: number;
+    height?: number;
+    content: React.ReactNode;
+    /**
+     * Deep-link target inside the app — e.g. open Settings straight to
+     * "wallpaper". The app reads it via useWindowSection().
+     */
+    section?: string;
+}
+interface WindowEntry extends OpenWindowOptions {
+    slug: string;
+    rect: WindowRect;
+    minimized: boolean;
+    maximized: boolean;
+    z: number;
+    /** Bumps every time `section` is (re)targeted, so apps re-navigate even to the same section. */
+    sectionNonce: number;
+}
+interface WindowManagerContextValue {
+    windows: WindowEntry[];
+    open: (slug: string, opts: OpenWindowOptions) => void;
+    close: (slug: string) => void;
+    focus: (slug: string) => void;
+    minimize: (slug: string) => void;
+    /** Un-minimize + bring to front (without replacing content). */
+    restore: (slug: string) => void;
+    toggleMaximize: (slug: string) => void;
+    isOpen: (slug: string) => boolean;
+    isMinimized: (slug: string) => boolean;
+    /** Deep-link an already-open window to a section (bumps its nonce so apps re-navigate). */
+    setSection: (slug: string, section: string) => void;
+    /** @internal used by <WindowManager/> to persist drag/resize geometry. */
+    updateRect: (slug: string, rect: WindowRect) => void;
+}
+/** Section deep-link exposed to app window content. */
+interface WindowSection {
+    slug: string;
+    section?: string;
+    nonce: number;
+}
+/**
+ * Read the deep-link section targeted for the current app window (e.g. Settings
+ * opened straight to "wallpaper"). `nonce` changes on every (re)target — react
+ * to it so re-opening to the same section still navigates. Returns an empty
+ * section outside a window.
+ */
+declare function useWindowSection(): WindowSection;
+declare function WindowManagerProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+declare namespace WindowManagerProvider {
+    var displayName: string;
+}
+/** Access the window manager API. Must be used within <WindowManagerProvider>. */
+declare function useWindowManager(): WindowManagerContextValue;
+/**
+ * WindowManager — renders one <Window/> per open entry tracked by the
+ * nearest <WindowManagerProvider>. Place this once inside the desktop's
+ * content area (DesktopShell does this for you).
+ */
+declare function WindowManager(): React.JSX.Element;
+declare namespace WindowManager {
+    var displayName: string;
+}
+
+/** Minimal brand shape for the login crest (name may be bilingual). */
+interface OSLoginBrand {
+    name?: string | {
+        en: string;
+        ar: string;
+    };
+    tagline?: {
+        en: string;
+        ar: string;
+    };
+    icon?: React.ReactNode | null;
+}
+interface OSLoginScreenProps {
+    /** Wallpaper id from `theme/wallpapers.ts` (defaults to "aurora"). */
+    wallpaper?: string;
+    /**
+     * Optional background image URL, layered ON TOP of the gradient wallpaper
+     * (cover/center). If it fails to load, the gradient shows through — so the
+     * screen never ends up blank.
+     */
+    backgroundImage?: string;
+    language?: "en" | "ar";
+    brand?: OSLoginBrand;
+    className?: string;
+    authClient?: AuthClient;
+    onSuccess?: () => void;
+    /** Optional "Create account" affordance. */
+    onRegister?: () => void;
+    /** When set, renders LockScreen/PasswordLockScreen instead of the sign-in form. */
+    lockedUser?: (LockScreenUser | PasswordLockScreenUser) & {
+        usePassword?: boolean;
+    };
+    onUnlockPin?: (pin: string) => Promise<void>;
+    onUnlockPassword?: (creds: UnlockCredentials) => Promise<void>;
+    onSignOut?: () => void;
+    onForceLogout?: () => void;
+    hasTOTP?: boolean;
+}
+declare function OSLoginScreen({ wallpaper, backgroundImage, language, brand, className, authClient, onSuccess, onRegister, lockedUser, onUnlockPin, onUnlockPassword, onSignOut, onForceLogout, hasTOTP, }: OSLoginScreenProps): React.JSX.Element;
+declare namespace OSLoginScreen {
+    var displayName: string;
+}
+
+interface LaunchpadProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    apps: OSApp[];
+    /** Slugs currently pinned to the dock. */
+    pinned?: string[];
+    /** Slugs currently hidden from the desktop. */
+    hidden?: string[];
+    onLaunch: (slug: string) => void;
+    onPin?: (slug: string) => void;
+    onUnpin?: (slug: string) => void;
+    onAddToDesktop?: (slug: string) => void;
+    onRemoveFromDesktop?: (slug: string) => void;
+}
+declare function Launchpad({ open, onOpenChange, apps, pinned, hidden, onLaunch, onPin, onUnpin, onAddToDesktop, onRemoveFromDesktop, }: LaunchpadProps): React.JSX.Element | null;
+declare namespace Launchpad {
+    var displayName: string;
+}
+
+interface SpotlightProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    apps: OSApp[];
+    onLaunch: (slug: string) => void;
+}
+declare function Spotlight({ open, onOpenChange, apps, onLaunch }: SpotlightProps): React.JSX.Element | null;
+declare namespace Spotlight {
+    var displayName: string;
+}
+/** Small icon button that opens Spotlight (for the top bar). */
+declare function SpotlightTrigger({ onClick, className }: {
+    onClick: () => void;
+    className?: string;
+}): React.JSX.Element;
+
+interface NotificationCenterProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    notifications: OSNotification[];
+    unreadCount?: number;
+    onMarkRead?: (id: string) => void;
+    onMarkAllRead?: () => void;
+    onNavigate?: (url: string) => void;
+    /** Optional slot rendered at the top (e.g. a weather / calendar widget). */
+    header?: React.ReactNode;
+}
+declare function NotificationCenter({ open, onOpenChange, notifications, unreadCount, onMarkRead, onMarkAllRead, onNavigate, header, }: NotificationCenterProps): React.JSX.Element;
+declare namespace NotificationCenter {
+    var displayName: string;
+}
+
+export { type DesktopApi, type DesktopContextAction, DesktopContextMenu, type DesktopContextMenuProps, DesktopIcon, DesktopIconGrid, type DesktopIconGridProps, type DesktopIconProps, type DesktopPrefs, DesktopShell, type DesktopShellProps, Dock, type DockProps, type IconPos, Launchpad, type LaunchpadProps, NotificationBell, type NotificationBellProps, NotificationCenter, type NotificationCenterProps, type OSApp, type OSAppWindow, type OSLoginBrand, OSLoginScreen, type OSLoginScreenProps, type OSNotification, type OpenWindowOptions, Spotlight, type SpotlightProps, SpotlightTrigger, TogoMenu, type TogoMenuProps, TopBar, type TopBarProps, type UseOSAppsResult, type UseOSSessionResult, type WeatherCondition, type WeatherData, WeatherWidget, type WeatherWidgetProps, Window, WindowManager, type WindowManagerContextValue, WindowManagerProvider, type WindowProps, type WindowRect, type WindowSection, WindowSpinner, clampWindowRect, useOSApps, useOSSession, useWindowManager, useWindowSection };