@legit-sdk/react 0.1.6 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # @legit-sdk/react
 
-Thin React wrapper around `@legit-sdk/core` providing a provider for SDK initialization and a hook to work with file content and history.
+React hooks for `@legit-sdk/core` - local-first file editing with version control.
 
 ## Install
 
@@ -8,32 +8,29 @@ Thin React wrapper around `@legit-sdk/core` providing a provider for SDK initial
 pnpm add @legit-sdk/core @legit-sdk/react
 ```
 
-Peer dependencies: `react >=18`.
+**Peer dependencies:** `react >=18`
 
-## Quick start
-
-- Wrap your app with `LegitProvider` once.
-- Use `useLegitFile(path)` inside components to read/update a file and access history.
+## Usage
 
 ```tsx
-import React from 'react';
 import { LegitProvider, useLegitFile } from '@legit-sdk/react';
 
 function Editor() {
-  const { content, setContent, history, loading, error } =
-    useLegitFile('/doc.txt');
-  const [text, setText] = React.useState(content);
-
-  React.useEffect(() => setText(content), [content]);
+  const { content, setContent, history, loading } = useLegitFile(
+    '/document.txt',
+    { initialContent: 'Hello World' } // auto-create if missing
+  );
+  const [text, setText] = useState(content || '');
 
-  if (loading) return <div>Loading…</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  useEffect(() => setText(content || ''), [content]);
 
   return (
     <div>
-      <input value={text} onChange={e => setText(e.target.value)} />
+      <textarea value={text} onChange={e => setText(e.target.value)} />
       <button onClick={() => setContent(text)}>Save</button>
-      <div>History entries: {history.length}</div>
+      {history.map(h => (
+        <div key={h.oid}>{h.message}</div>
+      ))}
     </div>
   );
 }
@@ -49,24 +46,56 @@ export default function App() {
 
 ## API
 
-- `LegitProvider`: initializes a shared SDK instance and polls repository HEAD.
-- `useLegitFile(path: string)` returns:
-  - `content: string`
-  - `setContent(newText: string): Promise<void>`
-  - `history: HistoryItem[]`
-  - `getPastState(commitHash: string): Promise<string>`
-  - `loading: boolean`
-  - `error?: Error`
+### `LegitProvider`
+
+Wraps your app and initializes the SDK instance. Polls HEAD for changes.
+
+```tsx
+<LegitProvider>
+  <YourApp />
+</LegitProvider>
+```
+
+### `useLegitFile(path, options?)`
+
+Hook for file operations.
 
-You can also access the provider context via `useLegitContext()` for advanced scenarios.
+**Options:**
+
+- `initialContent?: string` - Auto-create file with this content if missing
+
+**Returns:**
+
+- `content: string | null` - Current file content
+- `setContent(text: string): Promise<void>` - Save and commit
+- `history: HistoryItem[]` - Commit history
+- `getPastState(oid: string): Promise<string>` - Read file at commit
+- `loading: boolean` - Loading state
+- `error?: Error` - Error state
+
+### `useLegitContext()`
+
+Access provider context (legitFs, head, loading, error).
 
 ## Types
 
-- `UseLegitFileReturn`
-- `LegitContextValue`, `LegitProviderProps`
-- `HistoryItem` is exported by `@legit-sdk/core` and used in the hook return type.
+```ts
+interface UseLegitFileOptions {
+  initialContent?: string;
+}
+
+type UseLegitFileReturn = {
+  content: string | null;
+  setContent: (text: string) => Promise<void>;
+  history: HistoryItem[];
+  getPastState: (oid: string) => Promise<string>;
+  loading: boolean;
+  error?: Error;
+  legitFs: LegitFs | null;
+};
+```
 
-## Notes
+## See Also
 
-- This package does not bundle `react` or `@legit-sdk/core`; install them in your app.
-- The provider should be mounted once at the root of your React tree.
+- [Starter Example](../../examples/react-starter) - Full working example
+- [Spec Documentation](./spec.md) - Detailed API documentation

package/dist/index.d.ts

@@ -14,6 +14,9 @@ interface LegitProviderProps {
 }
 declare const LegitProvider: ({ children }: LegitProviderProps) => react_jsx_runtime.JSX.Element;
 
+interface UseLegitFileOptions {
+    initialContent?: string;
+}
 type UseLegitFileReturn = {
     content: string | null;
     setContent: (newText: string) => Promise<void>;
@@ -23,7 +26,7 @@ type UseLegitFileReturn = {
     error?: Error;
     legitFs: Awaited<ReturnType<typeof initLegitFs>> | null;
 };
-declare function useLegitFile(path: string): UseLegitFileReturn;
+declare function useLegitFile(path: string, options?: UseLegitFileOptions): UseLegitFileReturn;
 
 export { LegitProvider, useLegitContext, useLegitFile };
-export type { LegitContextValue, LegitProviderProps, UseLegitFileReturn };
+export type { LegitContextValue, LegitProviderProps, UseLegitFileOptions, UseLegitFileReturn };

package/dist/index.js

@@ -1,4 +1,4 @@
 // @legit-sdk/react bundle (ESM)
 // Generated by esbuild
 
-var C=Object.defineProperty;var r=(i,e)=>C(i,"name",{value:e,configurable:!0});import{createContext as E,useContext as R,useEffect as H,useState as c,useRef as S}from"react";import{initLegitFs as I}from"@legit-sdk/core";import b from"memfs";import{jsx as T}from"react/jsx-runtime";var v=E({legitFs:null,loading:!0,head:null}),h=r(()=>R(v),"useLegitContext"),N=r(({children:i})=>{let[e,d]=c(null),[m,u]=c(!0),[g,p]=c(),[y,L]=c(null),l=S(null);return H(()=>{let a=!0,s;return r(async()=>{try{let o=await I(b,"/");return a?(d(o),u(!1),s=setInterval(async()=>{if(o)try{let t=await o.promises.readFile("/.legit/branches/main/.legit/head","utf8");t!==l.current&&(l.current=t,L(t))}catch(t){console.error("Polling head failed:",t)}},200),()=>clearInterval(s)):void 0}catch(o){a&&(p(o),u(!1))}},"initFs")(),()=>{a=!1,s&&clearInterval(s)}},[]),T(v.Provider,{value:{legitFs:e,loading:m,head:y,error:g},children:i})},"LegitProvider");import{useEffect as $,useState as f}from"react";function k(i){let{legitFs:e,error:d,head:m}=h(),[u,g]=f(null),[p,y]=f([]),[L,l]=f(!0),[a,s]=f();return $(()=>{if(!e)return;r(async()=>{l(!0);try{let[n,P]=await Promise.allSettled([e.promises.readFile(`/.legit/branches/main${i}`,"utf8"),e.promises.readFile("/.legit/branches/main/.legit/history","utf8")]),F=null;if(n.status==="fulfilled")F=n.value;else if(n.reason?.code&&n.reason.code==="ENOENT")F=null;else throw n.reason;let x=[];if(P.status==="fulfilled")try{x=JSON.parse(P.value)}catch{x=[]}g(F??null),y(x),s(void 0)}catch(n){s(n)}finally{l(!1)}},"load")()},[e,i,m]),{content:u,setContent:r(async t=>{e&&(await e.promises.writeFile(`/.legit/branches/main${i}`,t,"utf8"),g(t))},"save"),history:p,getPastState:r(async t=>{if(!e)return"";try{return await e.promises.readFile(`/.legit/commits/${t.slice(0,2)}/${t.slice(2)}${i}`,"utf8")}catch{return""}},"getPastState"),loading:L,error:a??d,legitFs:e}}r(k,"useLegitFile");export{N as LegitProvider,h as useLegitContext,k as useLegitFile};
+var T=Object.defineProperty;var s=(i,l)=>T(i,"name",{value:l,configurable:!0});import{createContext as U,useContext as z,useEffect as A,useState as F,useRef as $}from"react";import{initLegitFs as V}from"@legit-sdk/core";import k from"memfs";import{jsx as D}from"react/jsx-runtime";var N=U({legitFs:null,loading:!0,head:null}),E=s(()=>z(N),"useLegitContext"),_=500,J=s(({children:i})=>{let[l,e]=F(null),[x,y]=F(!0),[f,g]=F(),[P,m]=F(null),a=$(null);return A(()=>{let o=!0,d,u="";return s(async()=>{try{let n=await V(k,"/");if(!o)return;e(n),y(!1),d=setInterval(async()=>{if(!(!o||!n))try{let t=await n.promises.readFile("/.legit/branches/main/.legit/head","utf8");t!==u&&t!==a.current&&(u=t,a.current=t,m(t))}catch(t){o&&t?.code!=="ENOENT"&&console.error("Polling head failed:",t)}},_)}catch(n){o&&(g(n),y(!1))}},"initFs")(),()=>{o=!1,d&&clearInterval(d)}},[]),D(N.Provider,{value:{legitFs:l,loading:x,head:P,error:f},children:i})},"LegitProvider");import{useEffect as b,useState as h,useRef as R,useCallback as M}from"react";function q(i,l){let{legitFs:e,error:x,head:y}=E(),[f,g]=h(null),[P,m]=h([]),[a,o]=h(!0),[d,u]=h(),p=R(null),n=R(!1),t=R(!1);b(()=>{if(!e)return;let r=!1;return s(async()=>{o(!0);try{let L=`/.legit/branches/main${i}`,O="/.legit/branches/main/.legit/history",[v,w]=await Promise.allSettled([e.promises.readFile(L,"utf8"),e.promises.readFile(O,"utf8").catch(()=>"")]);if(r)return;let H=v.status==="fulfilled"?v.value:null,S=[];if(w.status==="fulfilled")try{let I=w.value;I&&(S=JSON.parse(I))}catch{}p.current===H&&(p.current=null),g(H),m(S),u(void 0)}catch(L){L?.code!=="ENOENT"?u(L):(g(null),m([]))}finally{r||o(!1)}},"load")(),()=>{r=!0}},[e,i,y]);let C=M(async r=>{if(e)try{p.current=r,await e.promises.writeFile(`/.legit/branches/main${i}`,r,"utf8"),g(r)}catch(c){throw p.current=null,u(c),c}},[e,i]);return b(()=>{n.current||t.current||!a&&f===null&&e&&l?.initialContent&&(t.current=!0,n.current=!0,s(async()=>{try{await C(l.initialContent)}catch(c){console.error("Failed to initialize file:",c),n.current=!1}finally{t.current=!1}},"initialize")())},[a,f,e,l?.initialContent,C]),{content:f,setContent:C,history:P,getPastState:s(async r=>{if(!e)return"";try{return await e.promises.readFile(`/.legit/commits/${r.slice(0,2)}/${r.slice(2)}${i}`,"utf8")}catch{return""}},"getPastState"),loading:a,error:d??x,legitFs:e}}s(q,"useLegitFile");export{J as LegitProvider,E as useLegitContext,q as useLegitFile};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legit-sdk/react",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "React wrapper for @legit-sdk/core",
   "type": "module",
   "main": "./dist/index.js",