craft-native 0.0.37

package/dist/api/macos-advanced.d.ts

@@ -0,0 +1,721 @@
+/**
+ * @fileoverview macOS Advanced Features API
+ * @description Advanced macOS-specific features including Touch Bar, Desktop Widgets,
+ * Stage Manager, Handoff/Continuity, Sidecar, and system integration.
+ * @module @craft-native/api/macos-advanced
+ */
+/**
+ * Touch Bar item types.
+ */
+export type TouchBarItemType = 'button' | 'label' | 'slider' | 'popover' | 'colorPicker' | 'scrubber' | 'segmentedControl' | 'spacer' | 'group';
+/**
+ * Touch Bar button item.
+ */
+export interface TouchBarButton {
+    type: 'button';
+    id: string;
+    label?: string;
+    icon?: string;
+    backgroundColor?: string;
+    accessibilityLabel?: string;
+}
+/**
+ * Touch Bar label item.
+ */
+export interface TouchBarLabel {
+    type: 'label';
+    id: string;
+    label: string;
+    textColor?: string;
+    accessibilityLabel?: string;
+}
+/**
+ * Touch Bar slider item.
+ */
+export interface TouchBarSlider {
+    type: 'slider';
+    id: string;
+    label?: string;
+    minValue: number;
+    maxValue: number;
+    value: number;
+    minAccessoryIcon?: string;
+    maxAccessoryIcon?: string;
+}
+/**
+ * Touch Bar color picker item.
+ */
+export interface TouchBarColorPicker {
+    type: 'colorPicker';
+    id: string;
+    selectedColor?: string;
+    availableColors?: string[];
+}
+/**
+ * Touch Bar scrubber item.
+ */
+export interface TouchBarScrubber {
+    type: 'scrubber';
+    id: string;
+    items: Array<{
+        label?: string;
+        icon?: string;
+    }>;
+    selectedIndex?: number;
+    mode: 'fixed' | 'free';
+    showsArrowButtons?: boolean;
+}
+/**
+ * Touch Bar segmented control.
+ */
+export interface TouchBarSegmentedControl {
+    type: 'segmentedControl';
+    id: string;
+    segments: Array<{
+        label?: string;
+        icon?: string;
+    }>;
+    selectedIndex?: number;
+    segmentStyle?: 'automatic' | 'rounded' | 'separated';
+}
+/**
+ * Touch Bar popover item.
+ */
+export interface TouchBarPopover {
+    type: 'popover';
+    id: string;
+    label?: string;
+    icon?: string;
+    items: TouchBarItem[];
+    showCloseButton?: boolean;
+}
+/**
+ * Touch Bar spacer.
+ */
+export interface TouchBarSpacer {
+    type: 'spacer';
+    size: 'small' | 'large' | 'flexible';
+}
+/**
+ * Touch Bar group.
+ */
+export interface TouchBarGroup {
+    type: 'group';
+    id: string;
+    items: TouchBarItem[];
+}
+/**
+ * Touch Bar item union type.
+ */
+export type TouchBarItem = TouchBarButton | TouchBarLabel | TouchBarSlider | TouchBarColorPicker | TouchBarScrubber | TouchBarSegmentedControl | TouchBarPopover | TouchBarSpacer | TouchBarGroup;
+/**
+ * Touch Bar API for MacBook Pro Touch Bar support.
+ *
+ * @example
+ * // Create a Touch Bar
+ * touchBar.set([
+ *   { type: 'button', id: 'play', icon: 'play.fill' },
+ *   { type: 'spacer', size: 'flexible' },
+ *   { type: 'slider', id: 'volume', minValue: 0, maxValue: 100, value: 50 },
+ *   { type: 'button', id: 'favorite', icon: 'heart.fill', backgroundColor: '#ff375f' }
+ * ])
+ *
+ * // Handle interactions
+ * touchBar.onTap('play', () => togglePlayback())
+ * touchBar.onSliderChange('volume', (value) => setVolume(value))
+ */
+export declare const touchBar: {
+    /**
+     * Check if Touch Bar is available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Set Touch Bar items.
+     */
+    set(items: TouchBarItem[]): void;
+    /**
+     * Update a specific item.
+     */
+    updateItem(id: string, updates: Partial<TouchBarItem>): void;
+    /**
+     * Clear Touch Bar.
+     */
+    clear(): void;
+    /**
+     * Register tap handler for button.
+     */
+    onTap(id: string, handler: () => void): void;
+    /**
+     * Register slider change handler.
+     */
+    onSliderChange(id: string, handler: (value: number) => void): void;
+    /**
+     * Register color picker change handler.
+     */
+    onColorChange(id: string, handler: (color: string) => void): void;
+    /**
+     * Register scrubber selection handler.
+     */
+    onScrubberSelect(id: string, handler: (index: number) => void): void;
+    /**
+     * Register segment selection handler.
+     */
+    onSegmentSelect(id: string, handler: (index: number) => void): void;
+    /**
+     * Show/hide escape key.
+     */
+    setEscapeKeyVisible(visible: boolean): void;
+};
+/**
+ * Widget family (size).
+ */
+export type WidgetFamily = 'systemSmall' | 'systemMedium' | 'systemLarge' | 'systemExtraLarge';
+/**
+ * Widget timeline entry.
+ */
+export interface WidgetTimelineEntry {
+    /** Entry date */
+    date: Date;
+    /** Widget content data */
+    content: Record<string, any>;
+    /** Relevance score (0-1) */
+    relevance?: number;
+}
+/**
+ * Widget configuration.
+ */
+export interface WidgetConfiguration {
+    /** Widget kind identifier */
+    kind: string;
+    /** Display name */
+    displayName: string;
+    /** Description */
+    description: string;
+    /** Supported families */
+    supportedFamilies: WidgetFamily[];
+    /** Configuration intent type (for configurable widgets) */
+    configurationIntent?: string;
+}
+/**
+ * Desktop Widgets API for macOS widgets (WidgetKit).
+ *
+ * @example
+ * // Register a widget
+ * desktopWidgets.register({
+ *   kind: 'weather',
+ *   displayName: 'Weather',
+ *   description: 'Shows current weather',
+ *   supportedFamilies: ['systemSmall', 'systemMedium']
+ * })
+ *
+ * // Provide timeline
+ * desktopWidgets.provideTimeline('weather', async (_context) => {
+ *   const weather = await fetchWeather()
+ *   return {
+ *     entries: [
+ *       { date: new Date(), content: { temp: weather.temp, condition: weather.condition } }
+ *     ],
+ *     policy: { type: 'after', date: new Date(Date.now() + 3600000) }
+ *   }
+ * })
+ *
+ * // Reload timeline
+ * await desktopWidgets.reloadTimeline('weather')
+ */
+export declare const desktopWidgets: {
+    /**
+     * Check if widgets are supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Register a widget configuration.
+     */
+    register(config: WidgetConfiguration): void;
+    /**
+     * Provide timeline for a widget.
+     */
+    provideTimeline(kind: string, provider: (context: {
+        family: WidgetFamily;
+        isPreview: boolean;
+    }) => Promise<{
+        entries: WidgetTimelineEntry[];
+        policy: {
+            type: "atEnd" | "never" | "after";
+            date?: Date;
+        };
+    }>): void;
+    /**
+     * Reload timeline for a widget.
+     */
+    reloadTimeline(kind: string): Promise<void>;
+    /**
+     * Reload all timelines.
+     */
+    reloadAllTimelines(): Promise<void>;
+    /**
+     * Get current widget configurations.
+     */
+    getCurrentConfigurations(kind: string): Promise<Array<{
+        widgetId: string;
+        family: WidgetFamily;
+        intent?: Record<string, any>;
+    }>>;
+    /**
+     * Handle widget URL.
+     */
+    onWidgetURL(kind: string, handler: (url: string, widgetFamily: WidgetFamily) => void): void;
+};
+/**
+ * Stage Manager API for window organization.
+ *
+ * @example
+ * // Check if Stage Manager is active
+ * const isActive = await stageManager.isActive()
+ *
+ * // Create a window set (group)
+ * await stageManager.createSet(['window1', 'window2'])
+ *
+ * // Listen for active set changes
+ * stageManager.onActiveSetChange((windowIds) => {
+ *   console.log('Active set:', windowIds)
+ * })
+ */
+export declare const stageManager: {
+    /**
+     * Check if Stage Manager is active.
+     */
+    isActive(): Promise<boolean>;
+    /**
+     * Check if Stage Manager is available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get the current active window set.
+     */
+    getActiveSet(): Promise<string[]>;
+    /**
+     * Create a window set.
+     */
+    createSet(windowIds: string[]): Promise<void>;
+    /**
+     * Add window to current set.
+     */
+    addToCurrentSet(windowId: string): Promise<void>;
+    /**
+     * Remove window from current set.
+     */
+    removeFromCurrentSet(windowId: string): Promise<void>;
+    /**
+     * Listen for active set changes.
+     */
+    onActiveSetChange(handler: (windowIds: string[]) => void): void;
+    /**
+     * Listen for Stage Manager enable/disable.
+     */
+    onStateChange(handler: (isActive: boolean) => void): void;
+};
+/**
+ * User activity for Handoff.
+ */
+export interface UserActivity {
+    /** Activity type (reverse domain notation) */
+    activityType: string;
+    /** Title shown to user */
+    title: string;
+    /** User info dictionary */
+    userInfo?: Record<string, any>;
+    /** Web page URL for Universal Links */
+    webpageURL?: string;
+    /** Whether activity should be indexed */
+    isEligibleForSearch?: boolean;
+    /** Whether activity should be handed off */
+    isEligibleForHandoff?: boolean;
+    /** Whether activity supports public indexing */
+    isEligibleForPublicIndexing?: boolean;
+    /** Keywords for search */
+    keywords?: string[];
+    /** Expiration date */
+    expirationDate?: Date;
+}
+/**
+ * Handoff/Continuity API for cross-device experiences.
+ *
+ * @example
+ * // Start an activity for Handoff
+ * handoff.startActivity({
+ *   activityType: 'com.myapp.editing-document',
+ *   title: 'Editing: My Document',
+ *   userInfo: { documentId: '123', scrollPosition: 500 },
+ *   webpageURL: 'https://myapp.com/doc/123'
+ * })
+ *
+ * // Handle continuing activity from another device
+ * handoff.onContinue((activity) => {
+ *   openDocument(activity.userInfo.documentId)
+ *   scrollTo(activity.userInfo.scrollPosition)
+ * })
+ *
+ * // Universal Clipboard
+ * const hasRemoteContent = await handoff.hasRemoteClipboardContent()
+ */
+export declare const handoff: {
+    /**
+     * Start a user activity for Handoff.
+     */
+    startActivity(activity: UserActivity): void;
+    /**
+     * Update the current activity.
+     */
+    updateActivity(updates: Partial<UserActivity>): void;
+    /**
+     * Invalidate (stop) the current activity.
+     */
+    invalidateActivity(): void;
+    /**
+     * Handle continuing an activity from another device.
+     */
+    onContinue(handler: (activity: UserActivity) => void): void;
+    /**
+     * Check if there's content on remote clipboard (Universal Clipboard).
+     */
+    hasRemoteClipboardContent(): Promise<boolean>;
+    /**
+     * Request AirDrop file transfer.
+     */
+    shareViaAirDrop(filePaths: string[]): Promise<boolean>;
+    /**
+     * Check if Handoff is available.
+     */
+    isAvailable(): Promise<boolean>;
+};
+/**
+ * Sidecar device info.
+ */
+export interface SidecarDevice {
+    /** Device identifier */
+    id: string;
+    /** Device name */
+    name: string;
+    /** Device model */
+    model: string;
+    /** Whether currently connected */
+    isConnected: boolean;
+}
+/**
+ * Sidecar API for iPad as second display.
+ *
+ * @example
+ * // Get available Sidecar devices
+ * const devices = await sidecar.getAvailableDevices()
+ *
+ * // Connect to a device
+ * await sidecar.connect(devices[0].id)
+ *
+ * // Move window to Sidecar display
+ * await sidecar.moveWindowToSidecar(windowId)
+ */
+export declare const sidecar: {
+    /**
+     * Check if Sidecar is available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get available Sidecar devices.
+     */
+    getAvailableDevices(): Promise<SidecarDevice[]>;
+    /**
+     * Get currently connected device.
+     */
+    getConnectedDevice(): Promise<SidecarDevice | null>;
+    /**
+     * Connect to a Sidecar device.
+     */
+    connect(deviceId: string): Promise<boolean>;
+    /**
+     * Disconnect from Sidecar.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Move a window to the Sidecar display.
+     */
+    moveWindowToSidecar(windowId: string): Promise<void>;
+    /**
+     * Listen for connection changes.
+     */
+    onConnectionChange(handler: (device: SidecarDevice | null) => void): void;
+};
+/**
+ * Spotlight searchable item.
+ */
+export interface SpotlightItem {
+    /** Unique identifier */
+    uniqueIdentifier: string;
+    /** Domain identifier (for grouping) */
+    domainIdentifier?: string;
+    /** Display title */
+    title: string;
+    /** Content description */
+    contentDescription?: string;
+    /** Thumbnail URL or path */
+    thumbnailURL?: string;
+    /** Keywords for search */
+    keywords?: string[];
+    /** Content type (UTI) */
+    contentType?: string;
+    /** URL to open when selected */
+    contentURL?: string;
+    /** Rating (0-5) */
+    rating?: number;
+    /** Relative importance */
+    rankingHint?: number;
+}
+/**
+ * Spotlight API for search integration.
+ *
+ * @example
+ * // Index items for Spotlight
+ * await spotlight.indexItems([
+ *   {
+ *     uniqueIdentifier: 'doc-123',
+ *     title: 'My Document',
+ *     contentDescription: 'Important notes about the project',
+ *     keywords: ['notes', 'project', 'important']
+ *   }
+ * ])
+ *
+ * // Delete items from index
+ * await spotlight.deleteItems(['doc-123'])
+ *
+ * // Handle Spotlight search result selection
+ * spotlight.onContinueActivity((identifier) => {
+ *   openDocument(identifier)
+ * })
+ */
+export declare const spotlight: {
+    /**
+     * Index items for Spotlight search.
+     */
+    indexItems(items: SpotlightItem[]): Promise<void>;
+    /**
+     * Delete items from Spotlight index.
+     */
+    deleteItems(identifiers: string[]): Promise<void>;
+    /**
+     * Delete all items in a domain.
+     */
+    deleteItemsInDomain(domainIdentifier: string): Promise<void>;
+    /**
+     * Delete all indexed items.
+     */
+    deleteAllItems(): Promise<void>;
+    /**
+     * Handle user selecting a Spotlight result.
+     */
+    onContinueActivity(handler: (identifier: string, userInfo?: Record<string, any>) => void): void;
+    /**
+     * Check indexing status.
+     */
+    getIndexingStatus(): Promise<{
+        isIndexing: boolean;
+        itemCount: number;
+    }>;
+};
+/**
+ * Quick Action definition.
+ */
+export interface QuickAction {
+    /** Action identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Icon (SF Symbol or path) */
+    icon?: string;
+    /** Input types this action accepts */
+    inputTypes: Array<'text' | 'url' | 'file' | 'image'>;
+}
+/**
+ * Quick Actions API for Services menu integration.
+ *
+ * @example
+ * // Register a quick action
+ * quickActions.register({
+ *   id: 'summarize-text',
+ *   title: 'Summarize with MyApp',
+ *   icon: 'text.alignleft',
+ *   inputTypes: ['text']
+ * })
+ *
+ * // Handle quick action invocation
+ * quickActions.onInvoke('summarize-text', async (input) => {
+ *   const summary = await summarize(input.text)
+ *   return { result: summary }
+ * })
+ */
+export declare const quickActions: {
+    /**
+     * Register a quick action.
+     */
+    register(action: QuickAction): void;
+    /**
+     * Unregister a quick action.
+     */
+    unregister(actionId: string): void;
+    /**
+     * Handle quick action invocation.
+     */
+    onInvoke(actionId: string, handler: (input: {
+        text?: string;
+        url?: string;
+        filePaths?: string[];
+    }) => Promise<{
+        result?: string;
+        error?: string;
+    }>): void;
+};
+/**
+ * Share Extension API.
+ *
+ * @example
+ * // Handle share extension invocation
+ * shareExtension.onReceive((items) => {
+ *   for (const item of items) {
+ *     if (item.type === 'url') {
+ *       saveBookmark(item.url)
+ *     }
+ *   }
+ * })
+ */
+export declare const shareExtension: {
+    /**
+     * Handle receiving shared items.
+     */
+    onReceive(handler: (items: Array<{
+        type: "text" | "url" | "image" | "file";
+        text?: string;
+        url?: string;
+        filePath?: string;
+        mimeType?: string;
+    }>) => void): void;
+    /**
+     * Complete the share action.
+     */
+    complete(success?: boolean): Promise<void>;
+    /**
+     * Cancel the share action.
+     */
+    cancel(): Promise<void>;
+};
+/**
+ * Window tab group.
+ */
+export interface WindowTabGroup {
+    /** Tab group identifier */
+    id: string;
+    /** Windows in this group */
+    windowIds: string[];
+    /** Active window index */
+    activeIndex: number;
+}
+/**
+ * Advanced Window Management API.
+ *
+ * @example
+ * // Enable native tabs
+ * windowManagement.enableTabs()
+ *
+ * // Create a new tab
+ * await windowManagement.newTab()
+ *
+ * // Enter full screen
+ * await windowManagement.enterFullScreen()
+ *
+ * // Set up split view
+ * await windowManagement.createSplitView(window1Id, window2Id)
+ */
+export declare const windowManagement: {
+    /**
+     * Enable native window tabs.
+     */
+    enableTabs(): void;
+    /**
+     * Disable native window tabs.
+     */
+    disableTabs(): void;
+    /**
+     * Create a new tab.
+     */
+    newTab(url?: string): Promise<string>;
+    /**
+     * Close current tab.
+     */
+    closeTab(): Promise<void>;
+    /**
+     * Get tab groups.
+     */
+    getTabGroups(): Promise<WindowTabGroup[]>;
+    /**
+     * Select a tab.
+     */
+    selectTab(windowId: string): Promise<void>;
+    /**
+     * Move tab to new window.
+     */
+    moveTabToNewWindow(windowId: string): Promise<void>;
+    /**
+     * Merge all windows.
+     */
+    mergeAllWindows(): Promise<void>;
+    /**
+     * Enter full screen mode.
+     */
+    enterFullScreen(): Promise<void>;
+    /**
+     * Exit full screen mode.
+     */
+    exitFullScreen(): Promise<void>;
+    /**
+     * Toggle full screen.
+     */
+    toggleFullScreen(): Promise<void>;
+    /**
+     * Create split view with two windows.
+     */
+    createSplitView(leftWindowId: string, rightWindowId: string): Promise<void>;
+    /**
+     * Exit split view.
+     */
+    exitSplitView(): Promise<void>;
+    /**
+     * Tile window to left half.
+     */
+    tileLeft(): Promise<void>;
+    /**
+     * Tile window to right half.
+     */
+    tileRight(): Promise<void>;
+    /**
+     * Move window to space.
+     */
+    moveToSpace(spaceIndex: number): Promise<void>;
+    /**
+     * Register tab change handler.
+     */
+    onTabChange(handler: (tabGroup: WindowTabGroup) => void): void;
+    /**
+     * Register full screen change handler.
+     */
+    onFullScreenChange(handler: (isFullScreen: boolean) => void): void;
+};
+declare const macosAdvanced: {
+    touchBar: typeof touchBar;
+    desktopWidgets: typeof desktopWidgets;
+    stageManager: typeof stageManager;
+    handoff: typeof handoff;
+    sidecar: typeof sidecar;
+    spotlight: typeof spotlight;
+    quickActions: typeof quickActions;
+    shareExtension: typeof shareExtension;
+    windowManagement: typeof windowManagement;
+};
+export default macosAdvanced;
+//# sourceMappingURL=macos-advanced.d.ts.map