@rbxts/scribe-react 2.5.0 → 2.6.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ericplane
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 ericplane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Scribe-source-map.json

@@ -1 +1 @@
-{"version":"2.5.0","format":1,"description":"Segments are [packedLine, sourceLine]. Use the last segment at or before the packed line, then add its line offset.","files":{"addons/ui/ScribeReact.luau":{"sourceSha256":"129371347fee37556b753b9ba8c1ba7a20f4a5764c595b505cd53ec3d6b8eb0b","packedSha256":"6e85c1c51649d96cd3b8b3106766f782f1373103ffad31a5e1cbfea632127929","segments":[[1,1]],"packagePath":"init.luau"}}}
+{"version":"2.6.1","format":1,"description":"Segments are [packedLine, sourceLine]. Use the last segment at or before the packed line, then add its line offset.","files":{"addons/ui/ScribeReact.luau":{"sourceSha256":"f41d3f612836b11a19a9b01da12d276e10bd1887a57c086b4e985369825260c1","packedSha256":"f41d3f612836b11a19a9b01da12d276e10bd1887a57c086b4e985369825260c1","segments":[[1,1]],"packagePath":"init.luau"}}}

package/index.d.ts

@@ -1,16 +1,16 @@
-import type React = require("@rbxts/react");
-import type Scribe from "@rbxts/scribe";
-
-/** Bind the shared Luau adapter to the React installation used by your game. */
-declare function ScribeReact(react: Pick<typeof React, "useState" | "useEffect" | "useBinding">): ScribeReact.Adapter;
-
-declare namespace ScribeReact {
-	interface Adapter {
-		/** Use inside a component. Changes re-render the component. */
-		readonly useScribe: <T>(this: void, accessor: Scribe.ReadableNode<T>) => T;
-		/** Use inside a component. Changes update the binding without a re-render. */
-		readonly useScribeBinding: <T>(this: void, accessor: Scribe.ReadableNode<T>) => React.Binding<T>;
-	}
-}
-
-export = ScribeReact;
+import type React = require("@rbxts/react");
+import type Scribe from "@rbxts/scribe";
+
+/** Bind the shared Luau adapter to the React installation used by your game. */
+declare function ScribeReact(react: Pick<typeof React, "useState" | "useEffect" | "useBinding">): ScribeReact.Adapter;
+
+declare namespace ScribeReact {
+	interface Adapter {
+		/** Use inside a component. Changes re-render the component. */
+		readonly useScribe: <T>(this: void, accessor: Scribe.ReadableNode<T>) => T;
+		/** Use inside a component. Changes update the binding without a re-render. */
+		readonly useScribeBinding: <T>(this: void, accessor: Scribe.ReadableNode<T>) => React.Binding<T>;
+	}
+}
+
+export = ScribeReact;

package/init.luau

@@ -1,33 +1,74 @@
 --!strict
 -- React adapter. Copy into your game; not part of the Scribe package.
 --   local Scribe = require(path.to.ScribeReact)(React)
---   local coins = Scribe.useScribe(Data.Coins)          -- re-renders
---   local coins = Scribe.useScribeBinding(Data.Coins)   -- property only
---
--- useState + useEffect, not useSyncExternalStore: that is React 18 and jsdotlua
--- React 17.2.1 does not export it.
-
-return function(React: any)
-	local Adapter = {}
-
-	--- State tracking one accessor. Re-renders on every change.
-	function Adapter.useScribe(accessor: any): any
-		local value, setValue = React.useState(accessor.Get)
+--   local coins = Scribe.useScribe(Data.Coins)          -- number; re-renders
+--   local coins = Scribe.useScribeBinding(Data.Coins)   -- Binding<number>; property only
+-- Uses jsdotlua React 17.2.1 hooks.
+
+export type Disconnect = () -> ()
+
+export type Readable<T> = {
+	--[[
+	Returns the current value.
+	]]
+	read Get: () -> T,
+	--[[
+	Runs on future changes and returns a disconnect function.
+	]]
+	read Changed: (callback: (new: T, old: T) -> ()) -> Disconnect,
+}
+
+-- Matches react-lua's binding type.
+type CoreBinding<T> = {
+	--[[
+	Returns the current binding value.
+	]]
+	getValue: (self: CoreBinding<T>) -> T,
+	_source: string?,
+}
+type BindingMap = {
+	--[[
+	Creates a binding that transforms this binding's value.
+	]]
+	map: <T, U>(self: CoreBinding<T> & BindingMap, (T) -> U) -> BindingMap & CoreBinding<U>,
+}
+export type Binding<T> = CoreBinding<T> & BindingMap
+
+export type React = {
+	read useState: (initialState: any) -> (any, any),
+	read useEffect: (create: any, deps: any) -> (),
+	read useBinding: (initialValue: any) -> (any, any),
+}
+
+export type Adapter = {
+	--[[
+	Tracks an accessor and re-renders when it changes.
+	]]
+	useScribe: <T>(accessor: Readable<T>) -> T,
+	--[[
+	Updates a bound property without re-rendering.
+	]]
+	useScribeBinding: <T>(accessor: Readable<T>) -> Binding<T>,
+}
+
+--[[
+Creates React hooks for Scribe accessors.
+]]
+return function(React: React): Adapter
+	local function useScribe<T>(accessor: Readable<T>): T
+		local state: T, setValue: (T) -> () = React.useState(accessor.Get)
 		React.useEffect(function()
-			-- Re-read before subscribing: a write landing between render and effect is
-			-- otherwise missed, and the UI sits on the stale first value forever.
+			-- Catch writes between render and the effect.
 			setValue(accessor.Get())
 			return accessor.Changed(function(new)
 				setValue(new)
 			end)
 		end, { accessor })
-		return value
+		return state
 	end
 
-	--- A binding instead of state: updates the property without re-rendering. Prefer it
-	--- for a value that only feeds Text or Size.
-	function Adapter.useScribeBinding(accessor: any): any
-		local binding, setBinding = React.useBinding(accessor.Get())
+	local function useScribeBinding<T>(accessor: Readable<T>): Binding<T>
+		local binding: Binding<T>, setBinding: (T) -> () = React.useBinding(accessor.Get())
 		React.useEffect(function()
 			setBinding(accessor.Get())
 			return accessor.Changed(function(new)
@@ -37,5 +78,8 @@ return function(React: any)
 		return binding
 	end
 
-	return Adapter
+	return {
+		useScribe = useScribe,
+		useScribeBinding = useScribeBinding,
+	}
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/scribe-react",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Optional react addon for Scribe",
   "main": "init.luau",
   "types": "index.d.ts",
@@ -12,7 +12,7 @@
   "homepage": "https://scribe.ericplane.dev/",
   "author": "ericplane",
   "peerDependencies": {
-    "@rbxts/scribe": "^2.5.0",
+    "@rbxts/scribe": "^2.6.1",
     "@rbxts/react": "^17.0.0 || ^17.3.7-ts.2"
   },
   "publishConfig": {