@violetflux/kerros 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://violetflux.github.io/kerros/">
-    <img src="https://raw.githubusercontent.com/violetflux/kerros/main/docs/public/banner.svg" alt="Kerros — selector-first React stores" width="100%" />
+    <img src="https://raw.githubusercontent.com/violetflux/kerros/main/docs/public/banner.svg" alt="Kerros — share state between React components" width="100%" />
   </a>
 </p>
 
@@ -21,9 +21,9 @@
   <a href="https://github.com/violetflux/kerros/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@violetflux/kerros" alt="MIT license" /></a>
 </p>
 
-Kerros is a lightweight React state-sharing library based on Hooks and selectors.
+Kerros is a lightweight way to share state between React components.
 
-Write state as an ordinary custom Hook, wrap it with `createStore`, and share it below a Provider. Each component selects only the fields it uses.
+Write a Store the same way you write a custom Hook. When local state needs to be shared, pass it to `createStore`, mount its Provider, and let each component select what it needs.
 
 ## Install
 
@@ -36,6 +36,26 @@ Write state as an ordinary custom Hook, wrap it with `createStore`, and share it
 
 React 17, React 18, and React 19 are supported.
 
+## Why Kerros?
+
+- **Almost nothing new to learn** — reuse the React knowledge you already have; if you can write a custom Hook, you can write a Store
+- **Designed for flexible refactoring** — Stores and components use the same Hook API, so local state can become shared state with very little work
+- **Local and application-wide state** — Provider placement determines the Store scope, balancing flexibility with simplicity
+- **Avoid Context-wide rerenders** — Context carries a stable container and components rerender only when their selector result changes
+- **TypeScript support** — Store and selector types are inferred without duplicate declarations
+
+## From state management to state sharing
+
+Libraries such as Redux, Zustand, and Recoil can all share data, but their central job is still to organize state, update it, and define how data flows. “State management” is the right name for them.
+
+Kerros focuses on a smaller and more direct problem. It does not invent a new data model or prescribe how async logic should work. It answers one question: **how can a piece of Hook state be shared between React components?**
+
+Passing `value` and `onChange` through layer after layer damages component boundaries. Moving everything into one global Store does not automatically make an application scalable or maintainable either.
+
+Sharing frequently changing state through React Context directly also causes repeated work: every Context value change rerenders all consumers. Kerros keeps Provider scoping and multiple instances, but Context carries only a stable container. Components subscribe through selectors and rerender only when their selected result changes.
+
+Kerros stays simple, lightweight, and reliable. Write local state as an ordinary Hook, share it only when necessary, use a Provider to set its scope, and use selectors to choose what each component observes.
+
 ## Quick start
 
 ### Create a Store
@@ -111,15 +131,6 @@ function TaskList() {
 
 Kerros shallowly compares the selector object's top-level fields. When those selected fields stay equal, other Store updates do not rerender `TaskList`. The selector can stay inline and does not need `useCallback`.
 
-## Why Kerros?
-
-- **Just Hooks** — there are no reducers, actions, proxies, or new state syntax to learn
-- **Focused rerenders** — a component updates only when the fields returned by its selector change
-- **Provider scope** — mount a Store at the application root, inside a route, or around one widget
-- **Multiple instances** — every mounted Provider creates an isolated Store instance
-- **Store composition** — an inner Store can use an outer Store like any other Hook
-- **React 17–19** — one package works across all three React generations
-
 ## Multiple instances
 
 Each `TaskProvider` owns independent state:

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://violetflux.github.io/kerros/zh/">
-    <img src="https://raw.githubusercontent.com/violetflux/kerros/main/docs/public/banner.svg" alt="Kerros — selector 优先的 React Store" width="100%" />
+    <img src="https://raw.githubusercontent.com/violetflux/kerros/main/docs/public/banner.svg" alt="Kerros — 在 React 组件间共享状态" width="100%" />
   </a>
 </p>
 
@@ -14,9 +14,9 @@
   <a href="https://github.com/violetflux/kerros/blob/main/README.es.md">Español</a>
 </p>
 
-Kerros 是一个基于 React Hook 和 selector 的轻量状态共享库。
+Kerros 是一个在 React 组件间共享状态的轻量方案。
 
-你只需要用熟悉的 custom Hook 写状态，再用 `createStore` 包装一下，就能在 Provider 内的组件之间共享。每个组件通过 selector 选择自己使用的字段。
+你怎么写 custom Hook，就可以怎么写 Store。只有当局部状态需要被多个组件使用时，再交给 `createStore`，用 Provider 决定共享范围，用 selector 选择组件真正需要的数据。
 
 ## 安装
 
@@ -29,6 +29,26 @@ Kerros 是一个基于 React Hook 和 selector 的轻量状态共享库。
 
 支持 React 17、React 18 和 React 19。
 
+## 为什么要用 Kerros？
+
+- **几乎没有学习成本**：直接复用已有的 React 知识，你怎么写 custom Hook，就可以怎么写 Store
+- **为灵活重构而设计**：Store 和组件使用同一套 Hook API，可以近乎零成本地把组件局部状态转换成组件间共享状态
+- **同时支持局部状态和全局状态**：Provider 决定 Store 的作用域，在灵活和简单之间取得平衡
+- **解决 Context 的重复渲染问题**：Context 只传递稳定容器，selector 选择结果不变的组件不会重渲染
+- **优秀的 TypeScript 支持**：Store 和 selector 类型自动推断，不需要重复声明
+
+## 从状态管理到状态共享
+
+Redux、Zustand、Recoil 这些状态管理库当然也能解决数据共享问题，但它们最核心的能力仍然是组织数据、操作数据和约束数据流，因此它们应该被称为“状态管理”工具。
+
+Kerros 想解决的问题更小，也更直接。它不发明新的数据结构，不规定异步和数据流应该怎么写，只聚焦一个痛点：**如何在多个 React 组件间共享一段 Hook 状态。**
+
+层层传递 `value`、`onChange` 会逐渐破坏组件边界；粗暴地把数据全部塞进一个全局 Store，也不会自动让应用获得更好的扩展性和可维护性。
+
+直接用 React Context 共享变化频繁的状态也会带来重复渲染：Context value 每次变化，所有消费者都会更新。Kerros 保留 Provider 的作用域和多实例能力，但 Context 只传递稳定容器；组件通过 selector 订阅数据，只有选择结果变化时才重渲染。
+
+Kerros 简单、轻量、可靠。先把状态写成普通 Hook，需要共享时再交给 `createStore`；Provider 决定状态共享到哪里，selector 决定每个组件订阅什么。
+
 ## 快速上手
 
 ### 创建 Store
@@ -104,15 +124,6 @@ function TaskList() {
 
 Kerros 会浅比较 selector 返回对象的顶层字段。只要这些选中字段保持不变，Store 的其他更新就不会让 `TaskList` 重渲染。selector 可以直接写在调用位置，不需要 `useCallback`。
 
-## 为什么用 Kerros
-
-- **就是 Hook**：不需要学习 reducer、action、proxy 或新的状态语法
-- **精确重渲染**：只有 selector 返回的字段变化时组件才更新
-- **Provider 作用域**：Store 可以放在应用根部、路由内部或一个组件外层
-- **多个实例**：每个 Provider 都会创建独立的 Store
-- **Store 组合**：内层 Store 可以像普通 Hook 一样读取外层 Store
-- **React 17–19**：同一个包兼容三个 React 大版本
-
 ## 多个实例
 
 每个 `TaskProvider` 都拥有独立状态：

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@violetflux/kerros",
-  "version": "0.1.1",
-  "description": "A tiny selector-first React store built on useSyncExternalStore.",
+  "version": "0.1.3",
+  "description": "Hook-native state sharing for React with focused selector subscriptions.",
   "keywords": [
     "react",
     "react-hooks",