diff --git a/docsite/api/intro.md b/docsite/api/intro.md new file mode 100644 index 00000000000000..06c07fd761812b --- /dev/null +++ b/docsite/api/intro.md @@ -0,0 +1,10 @@ +--- +sidebar_position: 1 +slug: / +--- + +# macOS API Reference + +Welcome to the React Native macOS API reference documentation. This section covers macOS-specific props and events that extend the standard React Native components. + +Most of the additional functionality out of React Native macOS directly is in the form of additional props and callback events implemented on ``, to provide macOS and desktop specific behavior diff --git a/docsite/api/view-events.md b/docsite/api/view-events.md new file mode 100644 index 00000000000000..d4c1bf4a7fbe06 --- /dev/null +++ b/docsite/api/view-events.md @@ -0,0 +1,281 @@ +--- +sidebar_label: 'Events' +sidebar_position: 2 +--- + +# Events + +React Native macOS extends the standard React Native View component with additional events that are specific to macOS. These events allow you to respond to macOS-specific user interactions such as keyboard input, mouse movements, drag and drop operations, and more. + +## Focus + +This event is useful for implementing custom focus management and showing focus-specific UI elements. For these to fire, the prop [focusable](view-props#focusable) must be set. + +### `onFocus` + +Fired when the view receives focus. + +--- + +### `onBlur` + +Fired when the view loses focus. This is supported for all Views + +--- + + +## Keyboard + +### `onKeyDown` + +Fired when a key is pressed while the view has focus. + +**Event Data:** Key event with the following properties: +- `key`: The key value (aligned with [W3C UI Events](https://www.w3.org/TR/uievents-key/)) +- `altKey`: Whether Alt/Option key is pressed +- `ctrlKey`: Whether Control key is pressed +- `shiftKey`: Whether Shift key is pressed +- `metaKey`: Whether Command key is pressed +- `capsLockKey`: Whether Caps Lock is active +- `numericPadKey`: Whether the key is on the numeric keypad +- `helpKey`: Whether Help key is pressed +- `functionKey`: Whether a function key is pressed + +:::note +To receive key events, the view must have `focusable={true}` set, and you should specify which keys to handle using the `keyDownEvents` prop. +::: + +Example: +```javascript + { + const { key, metaKey } = event.nativeEvent; + if (key === 'Enter') { + console.log('Enter pressed'); + } else if (key === 's' && metaKey) { + console.log('Command+S pressed'); + } + }} +> + Press Enter or Cmd+S + +``` + +--- + +### `onKeyUp` + +Fired when a key is released while the view has focus. + +**Event Data:** Key event (same format as `onKeyDown`) + +:::note +To receive key events, the view must have `focusable={true}` set, and you should specify which keys to handle using the `keyUpEvents` prop. +::: + +--- + +## Mouse + +### `onMouseEnter` + +Fired when the mouse cursor enters the view's bounds. + +**Event Data:** Mouse event with the following properties: +- `clientX`: Horizontal position in the target view +- `clientY`: Vertical position in the target view +- `screenX`: Horizontal position in the window +- `screenY`: Vertical position in the window +- `altKey`: Whether Alt/Option key is pressed +- `ctrlKey`: Whether Control key is pressed +- `shiftKey`: Whether Shift key is pressed +- `metaKey`: Whether Command key is pressed + +Example: +```javascript + { + console.log('Mouse entered at', event.nativeEvent.clientX, event.nativeEvent.clientY); +}}> + Hover over me + +``` + +--- + +### `onMouseLeave` + +Fired when the mouse cursor leaves the view's bounds. + +**Event Data:** Mouse event (same format as `onMouseEnter`) + +Example: +```javascript + setIsHovered(true)} + onMouseLeave={() => setIsHovered(false)} + style={{ backgroundColor: isHovered ? 'lightblue' : 'white' }} +> + Hover state example + +``` + +--- + +### `onDoubleClick` + +Fired when the user double-clicks on the view. + +**Event Data:** Mouse event with the following properties: +- `clientX`: Horizontal position in the target view +- `clientY`: Vertical position in the target view +- `screenX`: Horizontal position in the window +- `screenY`: Vertical position in the window +- `altKey`: Whether Alt/Option key is pressed +- `ctrlKey`: Whether Control key is pressed +- `shiftKey`: Whether Shift key is pressed +- `metaKey`: Whether Command key is pressed + +Example: +```javascript + { + console.log('Double clicked at', event.nativeEvent.clientX, event.nativeEvent.clientY); +}}> + Double click me + +``` + +--- + +### `onDragEnter` + +Fired when a drag operation enters the view's bounds. + +**Event Data:** Drag event with mouse position and data transfer information + +This event is fired when the user drags content over the view. Use this to provide visual feedback that the view can accept the dragged content. + +--- + +### `onDragLeave` + +Fired when a drag operation leaves the view's bounds. + +**Event Data:** Drag event with mouse position and data transfer information + +This event is fired when the user drags content away from the view. Use this to remove any visual feedback shown during drag enter. + +--- + +### `onDrop` + +Fired when the user drops content onto the view. + +**Event Data:** Drag event with the following properties: +- Mouse position (`clientX`, `clientY`, `screenX`, `screenY`) +- Modifier keys (`altKey`, `ctrlKey`, `shiftKey`, `metaKey`) +- `dataTransfer`: Object containing: + - `files`: Array of dropped files, each with: + - `name`: File name + - `type`: MIME type + - `uri`: File URI + - `size`: File size (optional) + - `width`: Image width (optional, for images) + - `height`: Image height (optional, for images) + - `items`: Array of data transfer items, each with: + - `kind`: Item kind (e.g., 'file', 'string') + - `type`: MIME type + - `types`: Array of available data types + +Example: +```javascript + { + const files = event.nativeEvent.dataTransfer.files; + files.forEach(file => { + console.log('Dropped file:', file.name, file.uri); + }); + }} +> + Drop files here + +``` + +--- + +## Complete Example + +Here's a comprehensive example showing multiple macOS-specific events: + +```javascript +import React, { useState } from 'react'; +import { View, Text, StyleSheet } from 'react-native'; + +function MacOSEventsExample() { + const [status, setStatus] = useState('Ready'); + const [isHovered, setIsHovered] = useState(false); + + return ( + + setStatus('Focused')} + onBlur={() => setStatus('Blurred')} + onKeyDown={(e) => setStatus(`Key down: ${e.nativeEvent.key}`)} + onKeyUp={(e) => setStatus(`Key up: ${e.nativeEvent.key}`)} + onMouseEnter={(e) => { + setIsHovered(true); + setStatus(`Mouse entered at (${e.nativeEvent.clientX}, ${e.nativeEvent.clientY})`); + }} + onMouseLeave={() => { + setIsHovered(false); + setStatus('Mouse left'); + }} + onDoubleClick={() => setStatus('Double clicked!')} + onDragEnter={() => setStatus('Drag entered')} + onDragLeave={() => setStatus('Drag left')} + onDrop={(e) => { + const files = e.nativeEvent.dataTransfer.files; + setStatus(`Dropped ${files.length} file(s)`); + }} + > + Interactive macOS View + {status} + + + ); +} + + + height: 200, + backgroundColor: 'white', + borderWidth: 2, + borderColor: 'gray', + padding: 20, + }, + hoveredView: { + backgroundColor: 'lightblue', + }, + statusText: { + marginTop: 10, + fontStyle: 'italic', + }, +}); + +export default MacOSEventsExample; +``` diff --git a/docsite/api/view-props.md b/docsite/api/view-props.md new file mode 100644 index 00000000000000..21bd3f35d67bc2 --- /dev/null +++ b/docsite/api/view-props.md @@ -0,0 +1,177 @@ +--- +sidebar_label: 'Props' +sidebar_position: 1 +--- + +# Props + +React Native macOS extends the standard React Native `` component with additional props that are specific to macOS. These props allow you to customize the behavior and appearance of views to take advantage of macOS-specific features. + +## Props + +### `acceptsFirstMouse` + +Controls whether the view accepts the first mouse click when the window is inactive. + +| Type | Default | +| ---- | ------- | +| bool | `false` | + +When `true`, the view will respond to mouse clicks even when the window is not in focus, without first bringing the window to the foreground. + +--- + +### `allowsVibrancy` + +Enables the vibrancy effect for the view, allowing it to blend with the content behind the window. + +| Type | Default | +| ---- | ------- | +| bool | `false` | + +When `true`, the view will use macOS vibrancy effects, creating a translucent appearance that adapts to the content behind the window. This makes a difference when content is placed on top of a native [NSVisualEffectView](https://developer.apple.com/documentation/appkit/nsvisualeffectview), such as with the native module [VibrancyView](https://github.com/microsoft/fluentui-react-native/tree/main/packages/experimental/VibrancyView) + +--- + +### `cursor` + +Specifies the mouse cursor to display when hovering over the view. + +| Type | +| ------ | +| string | + +Sets the cursor style. This extends the React Native prop to support a larger range of the W3C cursor types supported on web. + +--- + +### `draggedTypes` + +Specifies the types of dragged content that the view accepts for drag and drop operations. + +| Type | +| --------------- | +| array of string | + +An array of UTI (Uniform Type Identifier) strings that the view will accept. Currently supported: `['fileUrl', 'image', 'string']`. + +--- + +### `enableFocusRing` + +Controls whether the standard macOS focus ring is displayed when the view has focus. + +| Type | Default | +| ---- | ------- | +| bool | `true` | + +When `true`, macOS will draw the standard focus ring around the view when it receives keyboard focus. + +--- + +### `focusable` + +Determines whether the view can receive keyboard focus. This prop has been extended from React Native Core to support all views. + +| Type | Default | +| ---- | ------- | +| bool | `false` | + +When `true`, the view can be focused using keyboard navigation (e.g., Tab key). + +--- + +### `keyDownEvents` + +Specifies which key down events should be handled by the view. + +| Type | +| ----------------------- | +| array of HandledKey | + +An array of key configurations that the view should handle. Each `HandledKey` object can specify: +- `key`: The key value (aligned with [W3C UI Events](https://www.w3.org/TR/uievents-key/)) +- `altKey` (optional): Whether Alt/Option key must be pressed +- `ctrlKey` (optional): Whether Control key must be pressed +- `shiftKey` (optional): Whether Shift key must be pressed +- `metaKey` (optional): Whether Command key must be pressed + +Example: +```javascript +keyDownEvents={[ + { key: 'Enter' }, + { key: 'a', metaKey: true } +]} +``` + +--- + +### `keyUpEvents` + +Specifies which key up events should be handled by the view. + +| Type | +| ----------------------- | +| array of HandledKey | + +An array of key configurations that the view should handle when keys are released. Uses the same format as `keyDownEvents`. + +--- + +### `mouseDownCanMoveWindow` + +Controls whether clicking and dragging on the view can move the window. + +| Type | Default | +| ---- | ------- | +| bool | `true` | + +When `true`, clicking and dragging on the view will allow the user to move the window. Set to `false` for interactive elements where you don't want this behavior. + +--- + +### `tooltip` + +Displays a tooltip when the user hovers over the view. + +| Type | +| ------ | +| string | + +The text to display in the tooltip. + +--- + +## Example Usage + +```javascript +import React from 'react'; +import { View, Text } from 'react-native'; + +function MacOSView() { + return ( + { + console.log('Key pressed:', event.nativeEvent.key); + }} + > + macOS View + + ); +} +``` + +## See Also + +- [View Events (macOS)](./view-events.md) - macOS-specific events for View components +- [React Native View Component](https://reactnative.dev/docs/view) - Base View component documentation diff --git a/docsite/docusaurus.config.ts b/docsite/docusaurus.config.ts index 3140529a8f9a5c..9d9f24e9897a06 100644 --- a/docsite/docusaurus.config.ts +++ b/docsite/docusaurus.config.ts @@ -47,6 +47,19 @@ const config: Config = { ], ], + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + id: 'api', + path: 'api', + routeBasePath: 'api', + sidebarPath: './sidebarsApi.ts', + editUrl: docsiteUrl + "/", + }, + ], + ], + themeConfig: { image: 'img/react-logo.svg', navbar: { @@ -62,6 +75,13 @@ const config: Config = { position: 'left', label: 'Docs', }, + { + type: 'docSidebar', + sidebarId: 'apiSidebar', + docsPluginId: 'api', + position: 'left', + label: 'API', + }, { label: "Blog", position: "right", diff --git a/docsite/sidebarsApi.ts b/docsite/sidebarsApi.ts new file mode 100644 index 00000000000000..aa2ca6fcd88871 --- /dev/null +++ b/docsite/sidebarsApi.ts @@ -0,0 +1,11 @@ +import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; + +const sidebars: SidebarsConfig = { + apiSidebar: [ + 'intro', + 'view-props', + 'view-events', + ], +}; + +export default sidebars;