@plasius/react-state 1.0.3 → 1.0.5

package/.github/workflows/cd.yml

@@ -2,8 +2,6 @@ name: CD (Publish to npm)
 
 on:
   workflow_dispatch:
-  release:
-    types: [published]
 
 permissions:
   contents: write
@@ -40,6 +38,9 @@ jobs:
           NEW_VER=$(npm version patch -m "chore: release v%s [skip ci]")
           echo "New version: $NEW_VER"
           git push --follow-tags
+          VER_NO_V=${NEW_VER#v}
+          echo "tag=$NEW_VER" >> "$GITHUB_OUTPUT"
+          echo "version=$VER_NO_V" >> "$GITHUB_OUTPUT"
 
           NAME=$(node -p "require('./package.json').name")
           echo "name=$NAME" >> "$GITHUB_OUTPUT"
@@ -49,6 +50,21 @@ jobs:
             echo "flags=--access public" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Create GitHub Release from tag (first-party)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.pkg.outputs.tag }}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists; skipping creation."
+          else
+            gh release create "$TAG" \
+              --title "Release $TAG" \
+              --generate-notes \
+              --latest
+          fi
+
       - name: Publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**, and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.
+
+---
+
+## [Unreleased]
+
+- **Added**
+  - (placeholder) Add new hooks, scoped store features, or context helpers here.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+---
+
+## [1.0.0] - 2025-09-16
+
+- **Added**
+
+  - Initial public release of `@plasius/react-state`.
+  - `createStore` for basic state container functionality with `dispatch`, `getState`, and subscription API.
+  - `createScopedStoreContext` for React integration:
+    - `<Provider>` component wrapping React trees,
+    - `useStore()` to access state,
+    - `useDispatch()` to dispatch actions.
+  - Support for per-key subscriptions and selector-based subscriptions.
+  - Unit tests with Vitest and component tests with React Testing Library.
+
+- **Changed**
+  - N/A (initial release)
+
+- **Fixed**
+  - N/A (initial release)
+
+---
+
+## Release process (maintainers)
+
+1. Update `CHANGELOG.md` under **Unreleased** with user‑visible changes.
+2. Bump version in `package.json` following SemVer (major/minor/patch).
+3. Move entries from **Unreleased** to a new version section with the current date.
+4. Tag the release in Git (`vX.Y.Z`) and push tags.
+5. Publish to npm (via CI/CD or `npm publish`).
+
+> Tip: Use Conventional Commits in PR titles/bodies to make changelog updates easier.
+
+---
+
+[Unreleased]: https://github.com/Plasius-LTD/react-state/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Plasius-LTD/react-state/releases/tag/v1.0.0

package/README.md

@@ -7,19 +7,29 @@
 [![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
 [![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
 
+---
+
 ## Overview
 
 `@plasius/react-state` provides a scoped state management solution for React applications. It allows developers to create isolated, testable, and composable stores without introducing heavy dependencies.
 
+---
+
 ## Installation
 
 ```bash
 npm install @plasius/react-state
 ```
 
+---
+
 ## Usage Example
 
+### Accessing the store
+
 ```tsx
+import { createStore } from '@plasius/react-state'
+
 type Action =
   | { type: "INCREMENT_VALUE"; payload: number }
   | { type: "SET_VALUE"; payload: number }
@@ -54,9 +64,81 @@ function doSomething() {
 }
 ```
 
+### Scoped react hooks
+
+```tsx
+import { createScopedStore } from '@plasius/react-state'
+
+type Action =
+  | { type: "INCREMENT_VALUE"; payload: number }
+  | { type: "SET_VALUE"; payload: number }
+  | { type: "DECREMENT_VALUE"; payload: number };
+
+interface State {
+  value: number;
+}
+
+const initialState: State = { value: 0 };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case "INCREMENT_VALUE":
+      return { ...state, value: state.value + action.payload };
+    case "DECREMENT_VALUE":
+      return { ...state, value: state.value - action.payload };
+    case "SET_VALUE":
+      // Distinct-until-changed: return the SAME reference if no change,
+      // so listeners relying on referential equality will not fire.
+      if (action.payload === state.value) return state;
+      return { ...state, value: action.payload };
+    default:
+      return state;
+  }
+}
+
+const store = createStore<State, Action>(reducer, initialState);
+
+const Counter = () => {
+    const state = store.useStore();
+    const dispatch = store.useDispatch();
+
+    return (
+      <div>
+        <button id="counter-inc" onClick={() => dispatch({ type: "inc" })}>
+          +
+        </button>
+        <button id="counter-dec" onClick={() => dispatch({ type: "dec" })}>
+          -
+        </button>
+        <input
+          aria-label="Counter value"
+          title=""
+          id="counter-set"
+          type="number"
+          value={state.count}
+          onChange={(e) =>
+            dispatch({ type: "set", payload: Number(e.target.value) })
+          }
+        />
+      </div>
+    );
+  };
+
+function App() { 
+  return (<><store.Provider><Counter /></store.Provider></>);
+}
+```
+
+---
+
 ## Contributing
 
-Contributions are welcome! Please read our [Code of Conduct](./CODE_OF_CONDUCT.md) and [Contributing Guide](./CONTRIBUTING.md) before submitting PRs.
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Contributor License Agreement](./legal/CLA.md)
+
+---
 
 ## License
 

package/docs/adrs/adr-0001: React store.md

@@ -0,0 +1,42 @@
+# ADR-0001: React State Store Purpose and Scope
+
+## Status
+
+- Proposed → Accepted
+- Date: 2025-09-12
+- Version: 1.0
+- Supersedes: N/A
+- Superseded by: N/A
+
+## Context
+
+Managing React application state across multiple components is a common challenge. Existing solutions (Redux, Zustand, Jotai, etc.) offer different trade-offs in complexity, ergonomics, and bundle size. For the Plasius ecosystem, we want:
+
+- A minimal, type-safe state container,
+- Strong integration with React via Context and Hooks,
+- Support for both global and scoped stores,
+- Predictable subscription and unsubscribe behaviour,
+- Alignment with SOLID principles and enterprise-grade maintainability.
+
+## Decision
+
+We will build a dedicated library, `@plasius/react-state`, that:
+
+- Provides a `createStore` primitive for basic state containers,
+- Provides `createScopedStoreContext` to integrate with React Context/Provider patterns,
+- Exposes hooks (`useStore`, `useDispatch`) to read state and dispatch actions,
+- Supports subscriptions: global, per-key, and selector-based,
+- Ensures distinct-until-changed semantics to avoid unnecessary re-renders,
+- Is published as an open source package under the Plasius-LTD organisation.
+
+## Consequences
+
+- **Positive:** Consistent and predictable state handling across Plasius projects, type-safe APIs, lighter alternative to Redux, improved testability, open source adoption possible.
+- **Negative:** Adds maintenance burden to keep feature parity with evolving React ecosystem; community may default to established libraries.
+- **Neutral:** Internal consumers may still choose other state management libs if required, but Plasius packages will standardise on this one.
+
+## Alternatives Considered
+
+- **Use Redux or Redux Toolkit:** Very mature, but verbose and heavier than desired.
+- **Use Zustand or Jotai:** Good ergonomics, but external dependency risk and less control over PII handling and subscription semantics.
+- **React Context alone:** Too minimal, lacking structured dispatch and subscribe/unsubscribe APIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/react-state",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Tiny, testable, typesafe React Scoped Store helper.",
   "keywords": [
     "react",