@fileverse-dev/dsheet 1.0.22 → 1.0.24

package/README.md

@@ -1,58 +1,187 @@
-# Dsheet Editor
+# Fileverse DSheet
 
-[dsheet.new](http://dsheet.new/) is your onchain, privacy-first alternative to G\**gle D*cs: peer-to-peer, end-to-end encrypted, and decentralized. It enables secure, real-time, and async collaboration without compromising user privacy.
+[![NPM](https://img.shields.io/npm/v/@fileverse-dev/dsheet)](https://www.npmjs.com/package/@fileverse-dev/dsheet)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-<img width="4410" alt="github_banner_final@3x" src="./package/assets/sheet.png" />
+Privacy-first, decentralized spreadsheet editor with real-time collaboration.
 
-This repository contains:
+[**Try Live Demo →**](https://fileverse-dsheet.vercel.app/)
 
-- `/package` – The core package code.
-- Example & demo source code to showcase dSheets functionalities.
+## Installation
 
-## Usage
+```bash
+npm install @fileverse-dev/dsheet
+```
+
+## Setup
 
-### Prequisites
+### 1. Import
 
-To use dSheet, ensure your project is set up with Tailwind CSS and have a Tailwind configuration file.
+```typescript
+import DsheetEditor from '@fileverse-dev/dsheet';
+import '@fileverse-dev/dsheet/styles';
+```
 
-### Install & import
+### 2. Configure Tailwind
 
-Add the following imports :
+Add to your `tailwind.config.js`:
 
 ```javascript
-import { DSheetEditor } from '@fileverse-dev/dsheet';
-import '@fileverse-dev/dsheet/styles'; // in App.jsx/App.tsx
+module.exports = {
+  content: [
+    "./src/**/*.{js,jsx,ts,tsx}",
+    "./node_modules/@fileverse-dev/dsheet/dist/index.es.js"
+  ]
+}
 ```
 
-### Update Tailwind Config
+### 3. Basic Usage
 
-In your tailwind config, add this line to content array :
+```typescript
+function App() {
+  const [data, setData] = useState({});
 
-`@fileverse-dev/dsheet/dist/index.es.js`
+  return (
+    <DsheetEditor
+      isAuthorized={true}
+      dsheetId="my-sheet-id"
+      onChange={(updateData) => setData(updateData)}
+    />
+  );
+}
+```
 
-You should now be set to use dSheets!
+## Props Reference
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isAuthorized` | `boolean` | Authorization status for the user |
+| `dsheetId` | `string` | Unique identifier for collaboration room |
+
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onChange` | `(data: SheetUpdateData, encodedUpdate?: string) => void` | - | Callback when sheet data changes |
+| `portalContent` | `string` | - | Encoded initial sheet data |
+| `isReadOnly` | `boolean` | `false` | Enable read-only mode |
+| `allowComments` | `boolean` | `false` | Enable comments (requires `isReadOnly=true`) |
+| `username` | `string` | - | Username for collaboration |
+| `isCollaborative` | `boolean` | `false` | Enable collaborative features |
+| `enableWebrtc` | `boolean` | `true` | Enable WebRTC for P2P collaboration |
+| `enableIndexeddbSync` | `boolean` | `true` | Enable local IndexedDB persistence |
+| `isTemplateOpen` | `boolean` | - | Template sidebar state |
+| `selectedTemplate` | `string` | - | Selected template identifier |
+| `onboardingComplete` | `boolean` | - | Onboarding completion status |
+| `sheetEditorRef` | `RefObject<WorkbookInstance>` | - | External ref to editor instance |
+
+### Advanced Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderNavbar` | `(editorValues?: EditorValues) => JSX.Element` | Custom navbar renderer |
+| `onboardingHandler` | `OnboardingHandlerType` | Custom onboarding logic |
+| `dataBlockApiKeyHandler` | `DataBlockApiKeyHandlerType` | API key handler for data blocks |
+| `getCommentCellUI` | `(row: number, column: number) => void` | Custom comment UI handler |
+| `commentData` | `Object` | Comment data for cells |
+| `toggleTemplateSidebar` | `() => void` | Template sidebar toggle handler |
+| `storeApiKey` | `(apiKeyName: string) => void` | API key storage handler |
+| `onDataBlockApiResponse` | `(dataBlockName: string) => void` | Data block API response handler |
+| `onDuneChartEmbed` | `() => void` | Dune chart embed handler |
+| `onSheetCountChange` | `(sheetCount: number) => void` | Sheet count change handler |
+
+### UI State Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `setShowFetchURLModal` | `Dispatch<SetStateAction<boolean>>` | URL fetch modal state setter |
+| `setFetchingURLData` | `(fetching: boolean) => void` | URL fetching state setter |
+| `setInputFetchURLDataBlock` | `Dispatch<SetStateAction<string>>` | URL input state setter |
+| `setForceSheetRender` | `Dispatch<SetStateAction<number>>` | Force re-render trigger |
+
+## Examples
+
+### Read-Only Viewer
+
+```typescript
+<DsheetEditor
+  isAuthorized={true}
+  dsheetId="viewer-sheet"
+  isReadOnly={true}
+  allowComments={true}
+  portalContent={encodedData}
+  onChange={() => {}}
+/>
+```
 
-# dSheetProps Interface
+### Collaborative Editor
+
+```typescript
+<DsheetEditor
+  isAuthorized={true}
+  dsheetId="collab-sheet"
+  username="john-doe"
+  isCollaborative={true}
+  enableWebrtc={true}
+  onChange={(data) => console.log('Sheet updated:', data)}
+/>
+```
+
+### Custom Navbar
+
+```typescript
+<DsheetEditor
+  isAuthorized={true}
+  dsheetId="custom-sheet"
+  renderNavbar={(editorValues) => (
+    <div className="flex items-center gap-4">
+      <h1>My Custom Sheet</h1>
+      <button onClick={() => editorValues?.sheetEditorRef.current?.exportToExcel()}>
+        Export
+      </button>
+    </div>
+  )}
+/>
+```
 
-The `DsheetProps` interface is a TypeScript interface that defines the properties for a page-related component. It includes properties for handling preview mode, managing publishing data, and optionally storing metadata and content associated with the page.
+### With Templates
 
-## Core Props
+```typescript
+<DsheetEditor
+  isAuthorized={true}
+  dsheetId="template-sheet"
+  selectedTemplate="financial-budget"
+  isTemplateOpen={true}
+  toggleTemplateSidebar={() => setTemplateOpen(!templateOpen)}
+/>
+```
 
-| Property                 | Type                                          | Description                                     |
-| ------------------------ | --------------------------------------------- | ----------------------------------------------- |
-| `portalContent`         | `JSONContent`                                 | Initial content of the editor                   |
-| `onChange`               | `(changes: JSONContent, chunk?: any) => void` | Callback triggered on editor content changes    |
-| `ref`                    | `React.RefObject`                             | Reference to access editor instance             |
-| `isReadOnly`          | `boolean`                                     | Controls if editor is in preview/read-only mode |
-| `allowComments`          | `boolean`                                     | Enables commenting in read-only mode - adds comment icon to toolbar and context menu (requires `isReadOnly=true`) |
-| `dsheetId`          | `string`                                     | Used as room id for collaboration |
+## Development
 
-### Steps to run this example locally
+### Run Demo
 
-- `cd demo`
-- `npm i`
-- `npm run dev`
+```bash
+cd demo
+npm install
+npm run dev
+```
+
+### Build Package
+
+```bash
+npm run build
+```
+
+## TypeScript
+
+All props are fully typed. Import types:
+
+```typescript
+import { DsheetProps, SheetUpdateData, EditorValues } from '@fileverse-dev/dsheet/types';
+```
 
-It will open up a vite server, that will have the Dsheet Editor.
+## License
 
-⚠️ This repository is currently undergoing rapid development, over the time more customization and API will be added.
+MIT