refactor: simplify browser hook return values

.changeset/browser-hook-return-shapes.md

@@ -0,0 +1,5 @@
+---
+'react-simplikit': major
+---
+
+`useKeyboardHeight`, `useVisualViewport`, and `useAvoidKeyboard` now return their single value directly instead of wrapping it in an object.

AGENTS.md

@@ -118,7 +118,7 @@ Never initialize state with browser API calls (causes hydration mismatch).
 - **Single value**: `useDebounce<T>(value, delay): T`
 - **Tuple** (2 items): `useToggle(init): [boolean, () => void]`
 - **Object** (3+ items): `usePagination(): { page, nextPage, prevPage }`
-- **Object** also when the shape is expected to grow: `useKeyboardHeight(): { keyboardHeight }`
+- **Single value** for browser measurements: `useKeyboardHeight(): number`
 
 ## Testing
 

CLAUDE.md

@@ -91,7 +91,7 @@ Never initialize state with browser API calls (causes hydration mismatch).
 - **Single value**: `useDebounce<T>(value, delay): T`
 - **Tuple** (state + action, 2 items): `useToggle(init): [boolean, () => void]`
 - **Object** (3+ items): `usePagination(): { page, nextPage, prevPage }`
-- **Object** also when the shape is expected to grow: browser measurements such as `useKeyboardHeight(): { keyboardHeight }`
+- **Single value** for browser measurements: `useKeyboardHeight(): number`
 
 ### Performance Patterns
 

README-es.md

@@ -66,7 +66,7 @@ Aplica el estilo que devuelve `useAvoidKeyboard` para mover un campo de entrada
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div style={{ position: 'fixed', bottom: 0, left: 0, right: 0, ...style }}>

README-ja_jp.md

@@ -66,7 +66,7 @@ function SearchInput() {
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div style={{ position: 'fixed', bottom: 0, left: 0, right: 0, ...style }}>

README-ko_kr.md

@@ -66,7 +66,7 @@ function SearchInput() {
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div style={{ position: 'fixed', bottom: 0, left: 0, right: 0, ...style }}>

README-zh_hans.md

@@ -66,7 +66,7 @@ function SearchInput() {
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div style={{ position: 'fixed', bottom: 0, left: 0, right: 0, ...style }}>

README.md

@@ -66,7 +66,7 @@ Use the style returned by `useAvoidKeyboard` to move a fixed input above the on-
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div style={{ position: 'fixed', bottom: 0, left: 0, right: 0, ...style }}>

docs/es/mobile-web.md

@@ -34,7 +34,7 @@ Este ejemplo mantiene un botón fijado en la parte inferior por encima del tecla
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div
@@ -61,7 +61,7 @@ import { useState } from 'react';
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
   const [message, setMessage] = useState('');
 
   return (
@@ -98,7 +98,7 @@ En los dispositivos con indicador de inicio (como el iPhone), puedes añadir un
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });
+  const style = useAvoidKeyboard({ safeAreaBottom: 34 });
 
   return (
     <div

docs/ja/mobile-web.md

@@ -34,7 +34,7 @@ npm install react-simplikit
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div
@@ -61,7 +61,7 @@ import { useState } from 'react';
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
   const [message, setMessage] = useState('');
 
   return (
@@ -98,7 +98,7 @@ function ChatInput() {
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });
+  const style = useAvoidKeyboard({ safeAreaBottom: 34 });
 
   return (
     <div

docs/ko/mobile-web.md

@@ -34,7 +34,7 @@ npm install react-simplikit
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div
@@ -61,7 +61,7 @@ import { useState } from 'react';
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
   const [message, setMessage] = useState('');
 
   return (
@@ -98,7 +98,7 @@ function ChatInput() {
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });
+  const style = useAvoidKeyboard({ safeAreaBottom: 34 });
 
   return (
     <div

docs/mobile-web.md

@@ -34,7 +34,7 @@ This example keeps a fixed bottom button above the keyboard.
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div
@@ -61,7 +61,7 @@ import { useState } from 'react';
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
   const [message, setMessage] = useState('');
 
   return (
@@ -98,7 +98,7 @@ For devices with home indicators (like iPhone), you can add a safe area offset:
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });
+  const style = useAvoidKeyboard({ safeAreaBottom: 34 });
 
   return (
     <div

docs/zh-Hans/mobile-web.md

@@ -34,7 +34,7 @@ npm install react-simplikit
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div
@@ -61,7 +61,7 @@ import { useState } from 'react';
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function ChatInput() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
   const [message, setMessage] = useState('');
 
   return (
@@ -98,7 +98,7 @@ function ChatInput() {
 import { useAvoidKeyboard } from 'react-simplikit';
 
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });
+  const style = useAvoidKeyboard({ safeAreaBottom: 34 });
 
   return (
     <div

examples/with-vite/src/pages/demos/UseVisualViewportDemo.tsx

@@ -7,7 +7,7 @@ import { DemoLayout } from '../../components/DemoLayout.tsx';
 const EXAMPLE_CODE = `import { useVisualViewport } from 'react-simplikit';
 
 function CustomLayout() {
-  const { viewport } = useVisualViewport();
+  const viewport = useVisualViewport();
 
   if (!viewport) {
     return <div>Not supported</div>;
@@ -28,7 +28,7 @@ function CustomLayout() {
 }`;
 
 export function UseVisualViewportDemo() {
-  const { viewport } = useVisualViewport();
+  const viewport = useVisualViewport();
   const [inputValue, setInputValue] = useState('');
 
   if (!viewport) {

packages/plugin/skills/react-simplikit/references/useAvoidKeyboard.md

@@ -7,9 +7,7 @@ to smoothly move them above the keyboard when it appears.
 ## Interface
 
 ```ts
-function useAvoidKeyboard(
-  options?: UseAvoidKeyboardOptions
-): UseAvoidKeyboardResult;
+function useAvoidKeyboard(options?: UseAvoidKeyboardOptions): CSSProperties;
 ```
 
 ### Parameters
@@ -55,24 +53,15 @@ function useAvoidKeyboard(
 
 <Interface
   name=""
-  type="UseAvoidKeyboardResult"
-  description="An object containing the CSS style for keyboard avoidance."
-  :nested="[
-    {
-      name: 'style',
-      type: 'CSSProperties',
-      required: false,
-      description:
-        'CSS style object to apply to the fixed bottom element. Contains <code>transform</code> and <code>transition</code> properties.',
-    },
-  ]"
+  type="CSSProperties"
+  description="The CSS style to apply to the fixed bottom element. Contains <code>transform</code> and <code>transition</code> properties."
 />
 
 ## Example
 
 ```tsx
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard();
+  const style = useAvoidKeyboard();
 
   return (
     <div
@@ -93,7 +82,7 @@ function FixedBottomCTA() {
 ```tsx
 // With safe area bottom offset (e.g., for iPhone home indicator)
 function FixedBottomCTA() {
-  const { style } = useAvoidKeyboard({ safeAreaBottom: 34 });
+  const style = useAvoidKeyboard({ safeAreaBottom: 34 });
 
   return (
     <div

packages/plugin/skills/react-simplikit/references/useKeyboardHeight.md

@@ -7,9 +7,7 @@ when the keyboard appears, disappears, or changes size.
 ## Interface
 
 ```ts
-function useKeyboardHeight(
-  options?: UseKeyboardHeightOptions
-): UseKeyboardHeightResult;
+function useKeyboardHeight(options?: UseKeyboardHeightOptions): number;
 ```
 
 ### Parameters
@@ -33,24 +31,15 @@ function useKeyboardHeight(
 
 <Interface
   name=""
-  type="UseKeyboardHeightResult"
-  description="An object containing the current keyboard height."
-  :nested="[
-    {
-      name: 'keyboardHeight',
-      type: 'number',
-      required: false,
-      description:
-        'The current keyboard height in pixels. 0 when the keyboard is hidden.',
-    },
-  ]"
+  type="number"
+  description="The current keyboard height in pixels. 0 when the keyboard is hidden."
 />
 
 ## Example
 
 ```tsx
 function ChatInput() {
-  const { keyboardHeight } = useKeyboardHeight();
+  const keyboardHeight = useKeyboardHeight();
 
   return (
     <div style={{ paddingBottom: `${keyboardHeight}px` }}>
@@ -62,7 +51,7 @@ function ChatInput() {
 
 ```tsx
 function KeyboardStatus() {
-  const { keyboardHeight } = useKeyboardHeight();
+  const keyboardHeight = useKeyboardHeight();
 
   return (
     <div>

packages/plugin/skills/react-simplikit/references/useVisualViewport.md

@@ -7,7 +7,7 @@ the keyboard appears or the user zooms/scrolls.
 ## Interface
 
 ```ts
-function useVisualViewport(): { viewport: VisualViewportState | null };
+function useVisualViewport(): VisualViewportState | null;
 ```
 
 ### Parameters
@@ -18,44 +18,37 @@ This function does not accept any parameters.
 
 <Interface
   name=""
-  type="{ viewport: VisualViewportState | null }"
-  description="An object containing the Visual Viewport state."
+  type="VisualViewportState | null"
+  description="The Visual Viewport state, or <code>null</code> if not supported (SSR or browsers without the Visual Viewport API);"
   :nested="[
     {
-      name: 'viewport',
-      type: 'VisualViewportState | null',
-      required: false,
-      description:
-        'Visual Viewport state object, or <code>null</code> if not supported (SSR or browsers without the Visual Viewport API).',
-    },
-    {
-      name: 'viewport.width',
+      name: 'width',
       type: 'number',
       required: false,
       description: 'Viewport width in pixels.',
     },
     {
-      name: 'viewport.height',
+      name: 'height',
       type: 'number',
       required: false,
       description: 'Viewport height in pixels.',
     },
     {
-      name: 'viewport.offsetLeft',
+      name: 'offsetLeft',
       type: 'number',
       required: false,
       description:
         'Viewport left offset in pixels from the layout viewport. Typically 0 unless horizontal scrolling or panning occurs.',
     },
     {
-      name: 'viewport.offsetTop',
+      name: 'offsetTop',
       type: 'number',
       required: false,
       description:
         'Viewport top offset in pixels from the layout viewport. Becomes negative on iOS when the keyboard appears (e.g., -300px means a 300px keyboard), so use <code>-offsetTop</code> for the keyboard height. Typically remains 0 on Android.',
     },
     {
-      name: 'viewport.scale',
+      name: 'scale',
       type: 'number',
       required: false,
       description:
@@ -68,7 +61,7 @@ This function does not accept any parameters.
 
 ```tsx
 function CustomLayout() {
-  const { viewport } = useVisualViewport();
+  const viewport = useVisualViewport();
 
   // Always check for null first
   if (!viewport) {
@@ -92,7 +85,7 @@ function CustomLayout() {
 ### Detecting zoom
 
 ```tsx
-const { viewport } = useVisualViewport();
+const viewport = useVisualViewport();
 if (viewport && viewport.scale > 1.3) {
   // Hide floating UI when user zooms in
   setShowFloatingButton(false);