docs: readme

Author: TimMikeladze

README.md

@@ -6,9 +6,9 @@ The File System Access API enables web applications to seamlessly work with file
 
 Unlike traditional file selection dialogs, the user will be prompted to select a directory, the hook will watch the files in that directory for changes - rerendering when changes are detected.
 
-Visit [**use-fs.com**](https://use-fs.app) to try it out.
+[**use-fs.com**](https://use-fs.app) to try it out.
 
-> ⚠️ Note: The File System API is not yet fully supported in all browsers yet. Works in Chrome, Edge and Opera.
+> ⚠️ Note: The File System API is not supported in all browsers. Works on Desktop in Chrome, Edge and Opera.
 
 ## 📡 Install
 
@@ -22,4 +22,115 @@ pnpm add use-fs
 
 > 👋 Hello there! Follow me [@linesofcode](https://twitter.com/linesofcode) or visit [linesofcode.dev](https://linesofcode.dev) for more cool projects like this one.
 
-## 🚀 Getting Started
+## 🚀 Getting Started
+
+```tsx
+import { useFs } from "use-fs";
+
+function App() {
+  const { 
+    onDirectorySelection, // Function to trigger directory selection dialog
+    files,               // Map of file paths to their contents
+    isBrowserSupported,  // Boolean indicating if File System API is supported
+    onClear,            // Function to clear selected directory and stop watching
+    isProcessing        // Boolean indicating if files are being processed
+  } = useFs({
+    // Optional array of filter functions to exclude files/directories. By default `commonFilters` is used to ignore .git, node_modules, etc.
+    filters: [
+      // Built-in filters available:
+      // - distFilter (excludes dist/, build/, node_modules/, etc.)
+      // - gitFilter (respects .gitignore)
+      // - miscFilter (excludes .DS_Store, etc.)
+      // Or use commonFilters which includes all of the above
+    ],
+    
+    // Called when new files are added to the watched directory
+    onFilesAdded: (newFiles, previousFiles) => {
+      console.log('Files added:', newFiles);
+      // newFiles: Map<string, string> - path -> content
+      // previousFiles: Map<string, string> - previous state
+    },
+
+    // Called when existing files are modified
+    onFilesChanged: (changedFiles, previousFiles) => {
+      console.log('Files changed:', changedFiles);
+      // changedFiles: Map<string, string> - path -> new content
+      // previousFiles: Map<string, string> - previous state
+    },
+
+    // Called when files are deleted from the watched directory
+    onFilesDeleted: (deletedFiles, previousFiles) => {
+      console.log('Files deleted:', deletedFiles);
+      // deletedFiles: Map<string, string> - path -> last known content
+      // previousFiles: Map<string, string> - previous state
+    },
+  });
+
+  if (!isBrowserSupported) {
+    return <div>Browser not supported</div>;
+  }
+
+  return (
+    <div>
+      <button 
+        onClick={onDirectorySelection}
+        disabled={isProcessing}
+      >
+        Select Directory
+      </button>
+
+      <button 
+        onClick={onClear}
+        disabled={isProcessing}
+      >
+        Clear
+      </button>
+
+      {files.size > 0 && (
+        <div>
+          <h2>Files ({files.size}):</h2>
+          <div>
+            {Array.from(files.entries()).map(([path, content]) => (
+              <div key={path}>
+                <h3>{path}</h3>
+                <pre>{content}</pre>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+The hook provides several key features:
+
+1. **File System Access**: Prompts users to select a directory and maintains access to it.
+2. **File Watching**: Continuously monitors selected directory for changes.
+3. **Content Management**: Provides access to file contents and updates in real-time.
+4. **Filtering**: Built-in and custom filters to exclude unwanted files/directories.
+5. **Performance Optimizations**: 
+   - Batched file processing
+   - Content caching
+   - Debounced updates
+   - Efficient change detection
+
+### Props
+
+- `filters?: FilterFn[]` - Array of filter functions to exclude files/directories
+- `onFilesAdded?: (newFiles: Map<string, string>, previousFiles: Map<string, string>) => void` - Callback when files are added
+- `onFilesChanged?: (changedFiles: Map<string, string>, previousFiles: Map<string, string>) => void` - Callback when files change
+- `onFilesDeleted?: (deletedFiles: Map<string, string>, previousFiles: Map<string, string>) => void` - Callback when files are deleted
+- `pollInterval?: number` - How often to check for changes (default: 100ms)
+- `batchSize?: number` - How many files to process in parallel (default: 50)
+- `debounceInterval?: number` - Debounce interval for updates (default: 50ms)
+- `fileCacheTtl?: number` - How long to cache file contents (default: 5000ms)
+
+### Return Values
+
+- `onDirectorySelection: () => Promise<void>` - Function to open directory picker
+- `onClear: () => void` - Function to stop watching and clear state
+- `files: Map<string, string>` - Current map of file paths to contents
+- `isProcessing: boolean` - Whether files are being processed
+- `isBrowserSupported: boolean` - Whether File System API is supported

docs/src/app/(home)/Demo.tsx

@@ -169,7 +169,7 @@ const App = () => {
 										.{" "}
 									</p>
 									<p className="mt-2 text-sm text-zinc-400 dark:text-zinc-600">
-										Supported in Chrome, Edge and Opera.
+										Supported on Desktop in Chrome, Edge and Opera.
 									</p>
 									<div className="mt-4">
 										<InstallCommand packageName="use-fs" />

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "use-fs",
-	"description": "A set of React hooks to interact with the File System API. Watch a directory for changes and return a map of filepaths & contents when a file is added, modified or removed.",
+	"description": "A React hook for integrating with the File System Access API. Enables web applications to seamlessly work with files on a user's local system.",
 	"version": "0.0.8",
 	"author": "Tim Mikeladze <[email protected]>",
 	"license": "MIT",