refactor: standardize state hook return values

.changeset/flat-state-hook-returns.md

@@ -0,0 +1,5 @@
+---
+'react-simplikit': major
+---
+
+Return a single object from `useBooleanState`, `useStorageState`, `useList`, `useMap`, and `useSet`. State values and actions are now named fields.

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

@@ -6,14 +6,12 @@ It provides functions to set the state to `true`, set it to `false`, and toggle
 ## Interface
 
 ```ts
-function useBooleanState(
-  initialValue: boolean | (() => boolean) = false
-): readonly [
-  state: boolean,
-  setTrue: () => void,
-  setFalse: () => void,
-  toggle: () => void,
-];
+function useBooleanState(initialValue: boolean | (() => boolean) = false): {
+  value: boolean;
+  setTrue: () => void;
+  setFalse: () => void;
+  toggle: () => void;
+};
 ```
 
 ### Parameters
@@ -28,11 +26,11 @@ function useBooleanState(
 
 <Interface
   name=""
-  type="readonly [state: boolean, setTrue: () => void, setFalse: () => void, toggle: () => void]"
-  description="A tuple containing:"
+  type="{ value: boolean; setTrue: () => void; setFalse: () => void; toggle: () => void }"
+  description="An object containing:"
   :nested="[
     {
-      name: 'state',
+      name: 'value',
       type: 'boolean',
       required: false,
       description: 'The current state value.',
@@ -61,6 +59,10 @@ function useBooleanState(
 ## Example
 
 ```tsx
-const [open, openBottomSheet, closeBottomSheet, toggleBottomSheet] =
-  useBooleanState(false);
+const {
+  value: open,
+  setTrue: openBottomSheet,
+  setFalse: closeBottomSheet,
+  toggle: toggleBottomSheet,
+} = useBooleanState(false);
 ```

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

@@ -18,7 +18,7 @@ function useList<T>(initialState: T[] = []): UseListReturn<T>;
 <Interface
   name=""
   type="UseListReturn<T>"
-  description="A tuple containing the array state and actions to manipulate it."
+  description="An object containing the array state and actions to manipulate it."
   :nested="[
     {
       name: 'list',
@@ -27,37 +27,37 @@ function useList<T>(initialState: T[] = []): UseListReturn<T>;
       description: 'The current array state.',
     },
     {
-      name: 'actions.push',
+      name: 'push',
       type: '(value: T) => void',
       required: false,
       description: 'Appends a value to the end of the list.',
     },
     {
-      name: 'actions.insertAt',
+      name: 'insertAt',
       type: '(index: number, value: T) => void',
       required: false,
       description: 'Inserts a value at the specified index.',
     },
     {
-      name: 'actions.updateAt',
+      name: 'updateAt',
       type: '(index: number, value: T) => void',
       required: false,
       description: 'Updates the value at the specified index.',
     },
     {
-      name: 'actions.removeAt',
+      name: 'removeAt',
       type: '(index: number) => void',
       required: false,
       description: 'Removes the value at the specified index.',
     },
     {
-      name: 'actions.setAll',
+      name: 'setAll',
       type: '(values: T[]) => void',
       required: false,
       description: 'Replaces the entire list with a new array.',
     },
     {
-      name: 'actions.reset',
+      name: 'reset',
       type: '() => void',
       required: false,
       description: 'Resets the list to its initial state.',
@@ -68,23 +68,24 @@ function useList<T>(initialState: T[] = []): UseListReturn<T>;
 ## Example
 
 ```tsx
-const [list, actions] = useList<string>(['apple', 'banana']);
+const { list, push, insertAt, updateAt, removeAt, setAll, reset } =
+  useList<string>(['apple', 'banana']);
 
 // Add an item
-actions.push('cherry');
+push('cherry');
 
 // Insert at index
-actions.insertAt(1, 'grape');
+insertAt(1, 'grape');
 
 // Update at index
-actions.updateAt(0, 'orange');
+updateAt(0, 'orange');
 
 // Remove at index
-actions.removeAt(2);
+removeAt(2);
 
 // Replace all
-actions.setAll(['kiwi', 'mango']);
+setAll(['kiwi', 'mango']);
 
 // Reset to initial state
-actions.reset();
+reset();
 ```

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

@@ -23,19 +23,19 @@ function useMap<K, V>(initialState: MapOrEntries<K, V>): UseMapReturn<K, V>;
 <Interface
   name=""
   type="UseMapReturn<K, V>"
-  description="A tuple containing the Map state and actions to manipulate it"
+  description="An object containing the Map state and actions to manipulate it"
 />
 
 ## Example
 
 ```tsx
-const [userMap, actions] = useMap<string, User>([
+const { map: userMap, set } = useMap<string, User>([
   ['user1', { name: 'John', age: 30 }],
 ]);
 
 // Using values from the Map
 const user1 = userMap.get('user1');
 
 // Updating the Map
-actions.set('user2', { name: 'Jane', age: 25 });
+set('user2', { name: 'Jane', age: 25 });
 ```

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

@@ -22,40 +22,40 @@ function useSet<T>(initialState: SetOrValues<T> = new Set()): UseSetReturn<T>;
 <Interface
   name=""
   type="UseSetReturn<T>"
-  description="A tuple containing the Set state and actions to manipulate it."
+  description="An object containing the Set state and actions to manipulate it."
   :nested="[
     {
-      name: '[0]',
+      name: 'set',
       type: 'Omit<Set<T>, \'add\' | \'clear\' | \'delete\'>',
       required: false,
       description: 'The current Set state with mutation methods hidden.',
     },
     {
-      name: '[1].add',
+      name: 'add',
       type: '(value: T) => void',
       required: false,
       description: 'Adds a value to the set.',
     },
     {
-      name: '[1].remove',
+      name: 'remove',
       type: '(value: T) => void',
       required: false,
       description: 'Removes a value from the set.',
     },
     {
-      name: '[1].toggle',
+      name: 'toggle',
       type: '(value: T) => void',
       required: false,
       description: 'Adds the value if absent, removes it if present.',
     },
     {
-      name: '[1].setAll',
+      name: 'setAll',
       type: '(values: Set<T> | T[]) => void',
       required: false,
       description: 'Replaces all values in the set.',
     },
     {
-      name: '[1].reset',
+      name: 'reset',
       type: '() => void',
       required: false,
       description: 'Resets the set to its initial state.',
@@ -69,7 +69,7 @@ function useSet<T>(initialState: SetOrValues<T> = new Set()): UseSetReturn<T>;
 import { useSet } from 'react-simplikit';
 
 function TagSelector() {
-  const [selectedTags, { add, remove, toggle }] = useSet<string>(['react']);
+  const { set: selectedTags, add, remove, toggle } = useSet<string>(['react']);
 
   return (
     <div>

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

@@ -9,11 +9,7 @@ The value is retained across page reloads and can be shared between tabs when us
 function useStorageState<T>(
   key: string,
   options?: Object
-): readonly [
-  state: Serializable<T> | undefined,
-  setState: (value: SetStateAction<Serializable<T> | undefined>) => void,
-  refreshState: () => void,
-];
+): StorageStateReturn<Serializable<T> | undefined>;
 ```
 
 ### Parameters
@@ -63,26 +59,26 @@ function useStorageState<T>(
 
 <Interface
   name=""
-  type="readonly [state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void, refreshState: () => void]"
-  description="A tuple:"
+  type="StorageStateReturn<Serializable<T> | undefined>"
+  description="An object containing:"
   :nested="[
     {
-      name: 'state',
+      name: 'value',
       type: 'Serializable<T> | undefined',
       required: false,
       description: 'The current state value retrieved from storage.',
     },
     {
-      name: 'setState',
+      name: 'setValue',
       type: '(value: SetStateAction<Serializable<T> | undefined>) => void',
       required: false,
-      description: 'A function to update and persist the state.',
+      description: 'Updates and persists the state.',
     },
     {
-      name: 'refreshState',
+      name: 'refresh',
       type: '() => void',
       required: false,
-      description: 'A function to refresh the state from storage.',
+      description: 'Refreshes the state from storage.',
     },
   ]"
 />
@@ -94,9 +90,12 @@ function useStorageState<T>(
 import { useStorageState } from 'react-simplikit';
 
 function Counter() {
-  const [count, setCount] = useStorageState<number>('counter', {
-    defaultValue: 0,
-  });
+  const { value: count, setValue: setCount } = useStorageState<number>(
+    'counter',
+    {
+      defaultValue: 0,
+    }
+  );
 
   return (
     <button onClick={() => setCount(prev => prev + 1)}>Count: {count}</button>

packages/react-simplikit/src/hooks/useBooleanState/es/useBooleanState.md

@@ -6,14 +6,12 @@ Proporciona funciones para establecer el estado en `true`, establecerlo en `fals
 ## Interfaz
 
 ```ts
-function useBooleanState(
-  initialValue: boolean | (() => boolean) = false
-): readonly [
-  state: boolean,
-  setTrue: () => void,
-  setFalse: () => void,
-  toggle: () => void,
-];
+function useBooleanState(initialValue: boolean | (() => boolean) = false): {
+  value: boolean;
+  setTrue: () => void;
+  setFalse: () => void;
+  toggle: () => void;
+};
 ```
 
 ### Parámetros
@@ -28,11 +26,11 @@ function useBooleanState(
 
 <Interface
   name=""
-  type="readonly [state: boolean, setTrue: () => void, setFalse: () => void, toggle: () => void]"
-  description="Una tupla que contiene:"
+  type="{ value: boolean; setTrue: () => void; setFalse: () => void; toggle: () => void }"
+  description="Un objeto que contiene:"
   :nested="[
     {
-      name: 'state',
+      name: 'value',
       type: 'boolean',
       required: false,
       description: 'El valor actual del estado.',
@@ -61,6 +59,10 @@ function useBooleanState(
 ## Ejemplo
 
 ```tsx
-const [open, openBottomSheet, closeBottomSheet, toggleBottomSheet] =
-  useBooleanState(false);
+const {
+  value: open,
+  setTrue: openBottomSheet,
+  setFalse: closeBottomSheet,
+  toggle: toggleBottomSheet,
+} = useBooleanState(false);
 ```

packages/react-simplikit/src/hooks/useBooleanState/ja/useBooleanState.md

@@ -6,14 +6,12 @@
 ## インターフェース
 
 ```ts
-function useBooleanState(
-  initialValue: boolean | (() => boolean) = false
-): readonly [
-  state: boolean,
-  setTrue: () => void,
-  setFalse: () => void,
-  toggle: () => void,
-];
+function useBooleanState(initialValue: boolean | (() => boolean) = false): {
+  value: boolean;
+  setTrue: () => void;
+  setFalse: () => void;
+  toggle: () => void;
+};
 ```
 
 ### パラメータ
@@ -28,11 +26,11 @@ function useBooleanState(
 
 <Interface
   name=""
-  type="readonly [state: boolean, setTrue: () => void, setFalse: () => void, toggle: () => void]"
-  description="以下を含むタプル。"
+  type="{ value: boolean; setTrue: () => void; setFalse: () => void; toggle: () => void }"
+  description="以下を含むオブジェクト。"
   :nested="[
     {
-      name: 'state',
+      name: 'value',
       type: 'boolean',
       required: false,
       description: '現在の状態の値。',
@@ -61,6 +59,10 @@ function useBooleanState(
 ## 使用例
 
 ```tsx
-const [open, openBottomSheet, closeBottomSheet, toggleBottomSheet] =
-  useBooleanState(false);
+const {
+  value: open,
+  setTrue: openBottomSheet,
+  setFalse: closeBottomSheet,
+  toggle: toggleBottomSheet,
+} = useBooleanState(false);
 ```