@ruby-native/react 0.10.14 → 0.10.22

package/README.md

@@ -39,18 +39,43 @@ Each component renders a hidden `data-native-*` signal element that the Ruby Nat
 - `NativeNavbar` - native navigation bar with title and buttons
 - `NativeButton` - native nav bar button (icon, title, href, or click target)
 - `NativeMenuItem` - item inside a native menu
+- `NativeShareButton` - native nav bar button that opens the share sheet
+- `NativeShareMenuItem` - menu item that opens the share sheet
 - `NativeSubmitButton` - native "Save" button that submits a form
+- `NativeFab` - floating action button
 - `NativeOverscroll` - per-page overscroll colors
 - `NativeBadge` - set the badge count on a home screen or tab bar icon
+- `NativeBackButton` - visible button that pops the native navigation stack
+
+`NativeBackButton` renders a chevron unless you pass children, and forwards extra props to the underlying `<button>`. An `onClick` handler runs first and can call `preventDefault()` to cancel the back:
+
+```jsx
+<NativeBackButton className="mr-2" aria-label="Go back" />
+```
 
 ## Helpers
 
+- `nativePlatform()` - returns `"ios"`, `"android"`, or `null` on the web. The counterpart of the `native_platform` Rails helper.
 - `nativeHaptic(feedback = "success", data = {})` - returns props to spread onto a clickable element so tapping it triggers native haptic feedback:
 
   ```jsx
   <button {...nativeHaptic("success")}>Save</button>
   ```
 
+## TypeScript
+
+Type declarations ship with the package. There is nothing to install and no `@types` companion package. Importing a component gives you autocomplete and prop checking:
+
+```tsx
+import { NativeNavbar, NativeButton } from "@ruby-native/react"
+
+<NativeNavbar title="Books" pullToRefresh={false}>
+  <NativeButton position="leading" icon="chevron.left" href="/books" />
+</NativeNavbar>
+```
+
+The `NativeIcons`, `NativeButtonPosition`, and `NativeHapticFeedback` types are exported too.
+
 ## Docs
 
 Full guides at [rubynative.com/docs](https://rubynative.com/docs).

package/index.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Returns "ios" or "android" inside a Ruby Native app, and null on the web.
+ * The counterpart of the `native_platform` Rails helper.
+ * @returns {"ios" | "android" | null}
+ */
+export function nativePlatform(): "ios" | "android" | null;
+/**
+ * @param {object} props
+ * @param {boolean} [props.enabled]
+ * @returns {import("react").ReactElement | null}
+ */
+export function NativeTabs({ enabled }: {
+    enabled?: boolean | undefined;
+}): import("react").ReactElement | null;
+/**
+ * @returns {import("react").ReactElement}
+ */
+export function NativePush(): import("react").ReactElement;
+/**
+ * @returns {import("react").ReactElement}
+ */
+export function NativeForm(): import("react").ReactElement;
+/**
+ * @returns {import("react").ReactElement}
+ */
+export function NativeReview(): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {boolean} [props.pullToRefresh]
+ * @param {import("react").ReactNode} [props.children]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeNavbar({ title, pullToRefresh, children }: {
+    title?: string | undefined;
+    pullToRefresh?: boolean | undefined;
+    children?: import("react").ReactNode;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {NativeButtonPosition} [props.position]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {string} [props.title]
+ * @param {string} [props.href]
+ * @param {string} [props.click]
+ * @param {boolean} [props.selected]
+ * @param {import("react").ReactNode} [props.children]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeButton({ position, icon, icons, title, href, click, selected, children }: {
+    position?: NativeButtonPosition | undefined;
+    icon?: string | undefined;
+    icons?: NativeIcons | undefined;
+    title?: string | undefined;
+    href?: string | undefined;
+    click?: string | undefined;
+    selected?: boolean | undefined;
+    children?: import("react").ReactNode;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {string} [props.href]
+ * @param {string} [props.click]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {boolean} [props.selected]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeMenuItem({ title, href, click, icon, icons, selected }: {
+    title?: string | undefined;
+    href?: string | undefined;
+    click?: string | undefined;
+    icon?: string | undefined;
+    icons?: NativeIcons | undefined;
+    selected?: boolean | undefined;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {NativeButtonPosition} [props.position]
+ * @param {string} [props.title]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {string} [props.url]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeShareButton({ position, title, icon, icons, url }: {
+    position?: NativeButtonPosition | undefined;
+    title?: string | undefined;
+    icon?: string | undefined;
+    icons?: NativeIcons | undefined;
+    url?: string | undefined;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {string} [props.url]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {boolean} [props.selected]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeShareMenuItem({ title, url, icon, icons, selected }: {
+    title?: string | undefined;
+    url?: string | undefined;
+    icon?: string | undefined;
+    icons?: NativeIcons | undefined;
+    selected?: boolean | undefined;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {string} [props.href]
+ * @param {string} [props.click]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeFab({ icon, icons, href, click }: {
+    icon?: string | undefined;
+    icons?: NativeIcons | undefined;
+    href?: string | undefined;
+    click?: string | undefined;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {string} props.top
+ * @param {string} [props.bottom]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeOverscroll({ top, bottom }: {
+    top: string;
+    bottom?: string | undefined;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {string} [props.click]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeSubmitButton({ title, click }: {
+    title?: string | undefined;
+    click?: string | undefined;
+}): import("react").ReactElement;
+/**
+ * @param {object} props
+ * @param {number} [props.count] Sets both `home` and `tab` unless they are given explicitly.
+ * @param {number} [props.home]
+ * @param {number} [props.tab]
+ * @returns {import("react").ReactElement}
+ */
+export function NativeBadge({ count, home, tab }: {
+    count?: number | undefined;
+    home?: number | undefined;
+    tab?: number | undefined;
+}): import("react").ReactElement;
+/**
+ * A visible button that pops the native navigation stack on tap. Renders a
+ * chevron unless you pass children. Extra props are forwarded to the button.
+ * An `onClick` handler runs first and may `preventDefault()` to cancel the pop.
+ * The counterpart of the `native_back_button_tag` Rails helper.
+ * @param {import("react").ButtonHTMLAttributes<HTMLButtonElement>} props
+ * @returns {import("react").ReactElement}
+ */
+export function NativeBackButton({ children, className, onClick, ...rest }: import("react").ButtonHTMLAttributes<HTMLButtonElement>): import("react").ReactElement;
+/**
+ * @param {NativeHapticFeedback} [feedback]
+ * @param {Record<string, unknown>} [data]
+ * @returns {Record<string, unknown>}
+ */
+export function nativeHaptic(feedback?: NativeHapticFeedback, data?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Per-platform icon names. iOS uses SF Symbols, Android uses Material icons.
+ */
+export type NativeIcons = {
+    ios?: string | undefined;
+    android?: string | undefined;
+};
+export type NativeHapticFeedback = "success" | "warning" | "error" | "impact" | "selection";
+export type NativeButtonPosition = "leading" | "trailing";

package/index.js

@@ -2,6 +2,21 @@ import { createElement } from "react"
 
 import("@inertiajs/react").then(m => { window.__inertiaRouter = m.router }).catch(() => {})
 
+/**
+ * Per-platform icon names. iOS uses SF Symbols, Android uses Material icons.
+ * @typedef {object} NativeIcons
+ * @property {string} [ios]
+ * @property {string} [android]
+ */
+
+/**
+ * @typedef {"success" | "warning" | "error" | "impact" | "selection"} NativeHapticFeedback
+ */
+
+/**
+ * @typedef {"leading" | "trailing"} NativeButtonPosition
+ */
+
 function rubyNativePlatform() {
   if (typeof navigator === "undefined") return null
   const ua = navigator.userAgent || ""
@@ -10,6 +25,11 @@ function rubyNativePlatform() {
   return null
 }
 
+/**
+ * @param {string} [icon]
+ * @param {NativeIcons} [icons]
+ * @returns {string | undefined}
+ */
 function resolveIcon(icon, icons) {
   if (icons) {
     const platform = rubyNativePlatform()
@@ -18,31 +38,89 @@ function resolveIcon(icon, icons) {
   return icon
 }
 
+/**
+ * Sends a message over the native bridge. Deliberately not exported: app code
+ * talks to the app through signal elements, not the raw message protocol.
+ * @param {Record<string, unknown>} message
+ * @returns {boolean}
+ */
+function postMessage(message) {
+  if (typeof window === "undefined") return false
+  const bridge = window.RubyNative
+  if (!bridge || typeof bridge.postMessage !== "function") return false
+  bridge.postMessage(message)
+  return true
+}
+
+/**
+ * Returns "ios" or "android" inside a Ruby Native app, and null on the web.
+ * The counterpart of the `native_platform` Rails helper.
+ * @returns {"ios" | "android" | null}
+ */
+export function nativePlatform() {
+  return rubyNativePlatform()
+}
+
+/**
+ * @param {object} props
+ * @param {boolean} [props.enabled]
+ * @returns {import("react").ReactElement | null}
+ */
 export function NativeTabs({ enabled = true }) {
   if (!enabled) return null
   return createElement("div", { "data-native-tabs": true, hidden: true })
 }
 
+/**
+ * @returns {import("react").ReactElement}
+ */
 export function NativePush() {
   return createElement("div", { "data-native-push": true, hidden: true })
 }
 
+/**
+ * @returns {import("react").ReactElement}
+ */
 export function NativeForm() {
   return createElement("div", { "data-native-form": true, hidden: true })
 }
 
+/**
+ * @returns {import("react").ReactElement}
+ */
 export function NativeReview() {
   return createElement("div", { "data-native-review": true, hidden: true })
 }
 
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {boolean} [props.pullToRefresh]
+ * @param {import("react").ReactNode} [props.children]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeNavbar({ title = "", pullToRefresh = true, children }) {
+  /** @type {Record<string, any>} */
   const props = { "data-native-navbar": title, hidden: true }
   if (!pullToRefresh) props["data-native-pull-to-refresh"] = "false"
   return createElement("div", props, children)
 }
 
+/**
+ * @param {object} props
+ * @param {NativeButtonPosition} [props.position]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {string} [props.title]
+ * @param {string} [props.href]
+ * @param {string} [props.click]
+ * @param {boolean} [props.selected]
+ * @param {import("react").ReactNode} [props.children]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeButton({ position = "trailing", icon, icons, title, href, click, selected, children }) {
   const resolved = resolveIcon(icon, icons)
+  /** @type {Record<string, any>} */
   const props = { "data-native-button": true }
   if (resolved) props["data-native-icon"] = resolved
   if (title) props["data-native-title"] = title
@@ -53,8 +131,19 @@ export function NativeButton({ position = "trailing", icon, icons, title, href,
   return createElement("div", props, children)
 }
 
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {string} [props.href]
+ * @param {string} [props.click]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {boolean} [props.selected]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeMenuItem({ title, href, click, icon, icons, selected }) {
   const resolved = resolveIcon(icon, icons)
+  /** @type {Record<string, any>} */
   const props = { "data-native-menu-item": true }
   if (title) props["data-native-title"] = title
   if (href) props["data-native-href"] = href
@@ -64,8 +153,18 @@ export function NativeMenuItem({ title, href, click, icon, icons, selected }) {
   return createElement("div", props)
 }
 
+/**
+ * @param {object} props
+ * @param {NativeButtonPosition} [props.position]
+ * @param {string} [props.title]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {string} [props.url]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeShareButton({ position = "trailing", title = "Share", icon = "square.and.arrow.up", icons, url }) {
   const resolved = resolveIcon(icon, icons)
+  /** @type {Record<string, any>} */
   const props = { "data-native-button": true, "data-native-share": "" }
   if (title) props["data-native-title"] = title
   if (resolved) props["data-native-icon"] = resolved
@@ -74,8 +173,18 @@ export function NativeShareButton({ position = "trailing", title = "Share", icon
   return createElement("div", props)
 }
 
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {string} [props.url]
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {boolean} [props.selected]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeShareMenuItem({ title = "Share", url, icon = "square.and.arrow.up", icons, selected }) {
   const resolved = resolveIcon(icon, icons)
+  /** @type {Record<string, any>} */
   const props = { "data-native-menu-item": true, "data-native-share": "", "data-native-title": title }
   if (url) props["data-native-share-url"] = url
   if (resolved) props["data-native-icon"] = resolved
@@ -83,15 +192,30 @@ export function NativeShareMenuItem({ title = "Share", url, icon = "square.and.a
   return createElement("div", props)
 }
 
+/**
+ * @param {object} props
+ * @param {string} [props.icon]
+ * @param {NativeIcons} [props.icons]
+ * @param {string} [props.href]
+ * @param {string} [props.click]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeFab({ icon, icons, href, click }) {
   const resolved = resolveIcon(icon, icons)
   if (!resolved) throw new Error("NativeFab requires `icon` or `icons`")
+  /** @type {Record<string, any>} */
   const props = { "data-native-fab": true, "data-native-icon": resolved, hidden: true }
   if (href) props["data-native-href"] = href
   if (click) props["data-native-click"] = click
   return createElement("div", props)
 }
 
+/**
+ * @param {object} props
+ * @param {string} props.top
+ * @param {string} [props.bottom]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeOverscroll({ top, bottom }) {
   return createElement("div", {
     "data-native-overscroll-top": top,
@@ -100,6 +224,12 @@ export function NativeOverscroll({ top, bottom }) {
   })
 }
 
+/**
+ * @param {object} props
+ * @param {string} [props.title]
+ * @param {string} [props.click]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeSubmitButton({ title = "Save", click = "[type='submit']" }) {
   return createElement("div", {
     "data-native-submit-button": true,
@@ -109,16 +239,51 @@ export function NativeSubmitButton({ title = "Save", click = "[type='submit']" }
   })
 }
 
+/**
+ * @param {object} props
+ * @param {number} [props.count] Sets both `home` and `tab` unless they are given explicitly.
+ * @param {number} [props.home]
+ * @param {number} [props.tab]
+ * @returns {import("react").ReactElement}
+ */
 export function NativeBadge({ count, home, tab }) {
   if (count != null && home == null) home = count
   if (count != null && tab == null) tab = count
+  /** @type {Record<string, any>} */
   const props = { "data-native-badge": "", hidden: true }
   if (home != null) props["data-native-badge-home"] = home
   if (tab != null) props["data-native-badge-tab"] = tab
   return createElement("div", props)
 }
 
+/**
+ * A visible button that pops the native navigation stack on tap. Renders a
+ * chevron unless you pass children. Extra props are forwarded to the button.
+ * An `onClick` handler runs first and may `preventDefault()` to cancel the pop.
+ * The counterpart of the `native_back_button_tag` Rails helper.
+ * @param {import("react").ButtonHTMLAttributes<HTMLButtonElement>} props
+ * @returns {import("react").ReactElement}
+ */
+export function NativeBackButton({ children, className, onClick, ...rest }) {
+  const classes = ["native-back-button", className].filter(Boolean).join(" ")
+  /** @param {import("react").MouseEvent<HTMLButtonElement>} event */
+  const handleClick = event => {
+    if (onClick) onClick(event)
+    if (!event.defaultPrevented) postMessage({ action: "back" })
+  }
+  const content = children != null ? children : createElement(
+    "svg",
+    { width: 24, height: 24, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2.5, "aria-hidden": true },
+    createElement("path", { d: "M15.75 19.5L8.25 12l7.5-7.5", strokeLinecap: "round", strokeLinejoin: "round" })
+  )
+  return createElement("button", { type: "button", ...rest, className: classes, onClick: handleClick }, content)
+}
+
+/**
+ * @param {NativeHapticFeedback} [feedback]
+ * @param {Record<string, unknown>} [data]
+ * @returns {Record<string, unknown>}
+ */
 export function nativeHaptic(feedback = "success", data = {}) {
   return { ...data, "data-native-haptic": feedback }
 }
-

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@ruby-native/react",
-  "version": "0.10.14",
+  "version": "0.10.22",
   "description": "React components for Ruby Native",
   "main": "index.js",
-  "files": ["index.js", "README.md"],
+  "types": "index.d.ts",
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "scripts": {
+    "types": "tsc -p .",
+    "prepublishOnly": "npm run types"
+  },
   "peerDependencies": {
     "react": ">=18",
     "@inertiajs/react": ">=2"
@@ -11,6 +16,10 @@
   "peerDependenciesMeta": {
     "@inertiajs/react": { "optional": true }
   },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "typescript": "^5.9.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/ruby-native/gem.git",