@materi.ai/frame 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,330 @@
+# Changelog
+
+All notable changes to `@materi.ai/frame` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-rc.1] - 2025-12-24 - 🚀 **Release Candidate**
+
+**🎯 Production-ready release candidate:** `npm install @materi.ai/frame@rc`
+
+### Major Improvements
+
+#### 📚 Complete Documentation Ecosystem (TASKSET 7)
+
+- **Comprehensive API Documentation**: TypeDoc integration with automated generation from TypeScript source
+- **Progressive Tutorial Series**: 9 tutorials from beginner to advanced (6+ hours of content)
+- **Real-World Examples**: Collaborative editor, spreadsheet calculator, component showcase
+- **15-Minute Quick Start**: Get running immediately with copy-paste examples
+- **Contributing Guidelines**: Complete development workflow and quality standards
+
+#### 🔧 Production Release Readiness (TASKSET 8)
+
+- **npm Publication Setup**: Complete registry configuration with automated publishing
+- **Release Automation**: Version management, changelog generation, and release workflows
+- **Quality Assurance**: Comprehensive testing, bundle validation, and integrity checks
+- **Monitoring Integration**: Download tracking, analytics, and error monitoring setup
+
+**🎉 Now available on npm:** `npm install @materi.ai/frame`
+
+**BREAKING:** This is the first stable release ready for npm publication. The API is now considered stable and production-ready.
+
+### 📦 Package Distribution
+
+- **Published to npm**: Available as `@materi.ai/frame` with full TypeScript support
+- **Tree-shakeable**: ESM modules with optimized bundling (`sideEffects: false`)
+- **Supply chain security**: npm provenance enabled for verified builds
+- **Unified exports**: Single package with subpath exports for all modules
+- **Documentation complete**: README, API reference, examples, and troubleshooting
+
+### Added
+
+#### Core Package
+
+- **Operational Transformation Engine** — Complete OT algorithm implementation with:
+    - `applyOp()` — Apply operations to document state
+    - `transform()` — Transform operations for concurrent edits
+    - `compose()` — Compose multiple operations
+    - Full support for string, array, and object mutations
+- **Formula Engine** — Spreadsheet formula parsing and evaluation:
+    - `parseFormula()` — Parse formula expressions
+    - `evaluateFormula()` — Evaluate formulas with cell references
+    - Support for basic and advanced functions (SUM, AVERAGE, IF, CONCAT, etc.)
+    - Type-safe formula results
+
+- **Type System** — Comprehensive TypeScript definitions:
+    - Document types (Cell, Sheet, Document, etc.)
+    - Operation types (Insert, Delete, Replace)
+    - User and collaboration types
+    - Formula and editor types
+
+- **WebSocket Manager** — Real-time connection handling:
+    - `WebSocketManager` class for connection lifecycle
+    - Message serialization/deserialization
+    - Automatic reconnection with exponential backoff
+    - Heartbeat/ping-pong support
+
+- **Presence System** — User presence and cursor tracking:
+    - Track active users and their cursors
+    - Broadcast user activity
+    - Presence list management
+
+- **Auth System** — Authentication and permission models:
+    - User authentication flows
+    - Permission checking
+    - Session management types
+
+- **Undo/Redo Manager** — Command-based undo/redo:
+    - `UndoManager` class for command history
+    - Undo/redo stack management
+    - Grouped commands support
+
+- **Search Infrastructure** — Full-text search support:
+    - Search query parsing
+    - Result ranking
+    - Index building
+
+#### UI Package
+
+- **Design Tokens** — Complete token system:
+    - Color palette (semantic and raw colors)
+    - Typography scale (fonts, sizes, weights, line heights)
+    - Spacing scale (consistent 4px-based spacing)
+    - Shadow system (elevation levels)
+    - Border radius and widths
+    - Transition timings and animations
+    - Dark mode support
+
+- **Primitive Components** — Accessible, unstyled base components:
+    - `Button` — Button with variants (primary, secondary, danger)
+    - `Input` — Text input with validation states
+    - `Select` — Dropdown select with keyboard support
+    - `Checkbox` — Accessible checkbox
+    - `Radio` — Radio button group
+    - `Dialog` — Modal dialog component
+    - `Tabs` — Tab navigation
+    - `Spinner` — Loading indicator
+    - `Badge` — Status badge
+    - `Toast` — Toast notification
+    - `Avatar` — User avatar with initials fallback
+
+- **High-Level Components**:
+    - `CollaborationUI` — Collaborative editing interface
+    - `CommandPalette` — Command/search interface
+    - `ErrorBoundary` — Error handling wrapper
+
+- **Editor Components**:
+    - `RichTextEditor` — Rich text editing interface
+    - `SpreadsheetEditor` — Spreadsheet interface
+    - `PresentationEditor` — Presentation editing interface
+
+- **Theme System**:
+    - Light and dark theme support
+    - `useTheme()` hook for theme switching
+    - Semantic color tokens
+    - CSS-in-JS and vanilla CSS compatible
+
+#### Hooks Package
+
+- **`useOT()`** — Manage operational transformation state
+    - Apply operations to local state
+    - Track pending operations
+    - Handle operation composition
+
+- **`useOTSync()`** — Synchronize OT state across clients
+    - Broadcast operations to server
+    - Apply remote operations locally
+    - Handle concurrent edits
+
+- **`useWebSocket()`** — WebSocket connection management
+    - Connect/disconnect lifecycle
+    - Send and receive messages
+    - Connection state tracking
+    - Auto-reconnection
+
+- **`useAuth()`** — Authentication state management
+    - User session tracking
+    - Login/logout flows
+    - Permission checking
+
+- **`useFetch()`** — Type-safe HTTP requests
+    - GET, POST, PUT, DELETE support
+    - Request caching
+    - Error handling
+
+- **`useCommandPalette()`** — Command palette state
+    - Open/close state
+    - Command search and filtering
+    - Command execution
+
+- **`useUndoRedo()`** — Undo/redo functionality
+    - Track command history
+    - Undo and redo operations
+    - History state exposure
+
+- **`useLocalStorage()`** — Persistent local state
+    - Sync with localStorage
+    - Type-safe storage access
+    - Automatic serialization
+
+- **`useForm()`** — Form state management
+    - Field state tracking
+    - Validation support
+    - Form submission handling
+
+- **`usePerformance()`** — Performance monitoring
+    - Render time tracking
+    - Memory usage monitoring
+    - Performance metrics export
+
+#### API Package
+
+- **HTTP Client** — Lightweight typed HTTP client:
+    - `createClient()` — Initialize HTTP client
+    - Request interceptors
+    - Response interceptors
+    - Error handling
+
+- **Endpoint Definitions** — Pre-defined typed API routes:
+    - Document management endpoints
+    - User endpoints
+    - Workspace endpoints
+    - Collaboration endpoints
+
+- **Result Type** — Type-safe API responses:
+    - Discriminated union for success/error
+    - Type inference for response data
+
+### Architecture
+
+- **Monorepo with Turbo** — Fast, cached builds with `turbo`
+- **TypeScript 5.3+** — Strict mode, full type safety
+- **ESM + CommonJS** — Dual module format
+- **Zero Runtime Dependencies** — Only React peer dependency
+- **Tree Shakeable** — Unused code eliminated by bundlers
+- **Distributed Types** — Full `.d.ts` generation
+- **Source Maps** — Debug-friendly source maps
+
+### Documentation
+
+- Comprehensive README with quick start guide
+- API documentation for all packages
+- Architecture highlights and design patterns
+- Development guide and testing setup
+- Troubleshooting section
+
+---
+
+## Versioning Strategy
+
+### Major Version (1.x.y)
+
+- Breaking changes to public API
+- Major architectural changes
+- New major features
+
+### Minor Version (x.1.y)
+
+- New features (backward compatible)
+- New components or hooks
+- API additions
+
+### Patch Version (x.y.1)
+
+- Bug fixes
+- Performance improvements
+- Documentation updates
+- Internal refactorings
+
+### Pre-release Versions
+
+- `1.0.0-alpha.1` — Early development
+- `1.0.0-beta.1` — Feature complete, testing phase
+- `1.0.0-rc.1` — Release candidate
+
+---
+
+## Release Process
+
+1. **Update Version Numbers**
+
+    ```bash
+    npm version major|minor|patch
+    ```
+
+2. **Update CHANGELOG** — Document changes in this file
+
+3. **Build & Test**
+
+    ```bash
+    pnpm build
+    pnpm test
+    pnpm type-check
+    ```
+
+4. **Publish**
+
+    ```bash
+    npm publish
+    ```
+
+5. **Tag Release**
+    ```bash
+    git tag v1.0.0
+    git push origin v1.0.0
+    ```
+
+---
+
+## Unreleased Changes
+
+### Planned Features
+
+- [ ] Official Storybook component gallery
+- [ ] GraphQL client integration
+- [ ] Offline-first synchronization strategy
+- [ ] Advanced formula functions (financial, statistical)
+- [ ] Rich text editor with collaborative cursors
+- [ ] End-to-end encryption support
+- [ ] Performance monitoring dashboard
+- [ ] Mobile-optimized components
+
+### Under Investigation
+
+- CRDT (Conflict-free Replicated Data Type) support
+- Lazy loading and code splitting optimizations
+- Custom rendering engines for editors
+- Plugin system for extensibility
+
+---
+
+## Deprecation Policy
+
+Deprecated features will:
+
+1. Be marked with `@deprecated` JSDoc comments
+2. Receive at least 2 minor version cycles of support
+3. Be removed in the next major version
+4. Include migration guides in documentation
+
+---
+
+## Known Limitations
+
+- Formula engine supports subset of Excel functions (expanding in minor versions)
+- WebSocket client requires TLS in production (http:// not supported)
+- Presence system limited to 1000 concurrent users per document
+- Search index limited to 1M documents (per session)
+
+---
+
+## Contributing
+
+See [Contributing Guide](../CONTRIBUTING.md) for development setup, commit message conventions, and pull request process.
+
+---
+
+**For more information, see [README.md](./README.md) and the [API Documentation](./docs/).**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Materi
+
+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.