@startsoft/lumina 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to @startsoft/lumina 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).
+
+## [1.0.0] - 2024-XX-XX
+
+### Added
+
+#### Core CRUD Hooks
+- `useModelIndex()` - Fetch paginated model lists with filtering, sorting, and search
+- `useModelShow()` - Fetch single model by ID with relationships
+- `useModelStore()` - Create new model instances
+- `useModelUpdate()` - Update existing models
+- `useModelDelete()` - Soft delete models (moves to trash)
+
+#### Soft Delete Operations
+- `useModelTrashed()` - Fetch soft-deleted models with pagination
+- `useModelRestore()` - Restore soft-deleted models
+- `useModelForceDelete()` - Permanently delete models (cannot be recovered)
+
+#### Advanced Features
+- `useNestedOperations()` - Execute multi-model transactions with reference support
+- `useModelAudit()` - Fetch audit trail for model instances
+
+#### Authentication & Organization
+- `useAuth()` - Authentication state and methods (login, logout, setOrganization)
+- `useOrganization()` - Get current organization slug from context
+- `useOwner()` - Fetch organization data with related users
+- `useOrganizationExists()` - Validate organization existence
+
+#### Invitations System
+- `useInvitations()` - List organization invitations with status filtering
+- `useInviteUser()` - Create new invitation
+- `useResendInvitation()` - Resend invitation email
+- `useCancelInvitation()` - Cancel pending invitation
+- `useAcceptInvitation()` - Accept invitation (public route)
+
+#### Query Features
+- **Pagination** - Automatic metadata extraction from response headers (X-Current-Page, X-Last-Page, X-Per-Page, X-Total)
+- **Filtering** - Field-level filters with `filter[field]=value` syntax
+- **Search** - Full-text search across models
+- **Relationships** - Eager loading with `includes` parameter
+- **Field Selection** - Select specific fields to reduce payload size
+- **Sorting** - Sort by any field (ascending/descending with `-` prefix)
+- **Multi-tenant Routing** - Organization-based URL routing
+
+#### Utilities
+- `extractPaginationFromHeaders()` - Parse pagination metadata from API responses
+- Configured Axios client with:
+  - Base URL configuration via environment variables
+  - Bearer token injection from localStorage
+  - CORS support with credentials
+  - 401 auto-logout and redirect
+  - Request/response interceptors
+
+#### Infrastructure
+- **TanStack Query 5.62.11** - Data fetching, caching, and state management
+- **React 19 support** - Compatible with latest React features
+- **TypeScript support** - Full type definitions and IntelliSense
+- **Barrel exports** - Clean import paths from `@startsoft/lumina`
+- **Comprehensive documentation** - API reference, guides, and examples
+- **Example components** - Demo components for testing features
+
+### Changed
+- `useModelIndex` now returns `{ data, pagination }` instead of just `data` for consistency
+- All hooks use organization context from `useOrganization()` for multi-tenancy
+- React Query cache keys include organization and options for proper isolation
+
+### Infrastructure
+- Built with Vite 6.0.1 for fast development and optimized builds
+- ESLint 9 with React and React Hooks plugins
+- Tailwind CSS 3.4.0 with dark mode support
+- Radix UI components for accessible UI primitives
+
+## [Unreleased]
+
+### Planned Features
+- **WebSocket Support** - Real-time updates for model changes
+- **Offline Mode** - Queue operations and sync when online
+- **Advanced Caching** - Configurable cache strategies per model
+- **Optimistic Updates** - Helpers for optimistic UI updates
+- **File Uploads** - Dedicated hooks for file upload with progress
+- **Batch Operations** - Bulk create, update, delete operations
+- **Query Builder UI** - Visual query builder component
+- **Subscriptions** - Model subscription for live updates
+
+### Planned Improvements
+- **Performance** - Virtual scrolling for large lists
+- **DevTools** - React Query DevTools integration
+- **Testing** - Jest/Vitest setup with testing utilities
+- **Storybook** - Component documentation and testing
+- **CI/CD** - Automated testing and npm publishing
+
+---
+
+## Version History
+
+- **1.0.0** - Initial release with complete CRUD, soft deletes, nested operations, pagination, and multi-tenant support
+
+---
+
+## Migration Guides
+
+### Upgrading to 1.0.0
+
+If you were using the template/demo version, you'll need to update imports:
+
+**Before:**
+```typescript
+import { useModelIndex } from './hooks/useModel';
+```
+
+**After:**
+```typescript
+import { useModelIndex } from '@startsoft/lumina';
+```
+
+**Breaking Changes:**
+- `useModelIndex` now returns `{ data, pagination }` instead of direct array
+  - Update: `const users = useModelIndex('users')` → `const { data: response } = useModelIndex('users'); const users = response?.data || [];`
+
+---
+
+## Support
+
+- [Documentation](./docs/)
+- [Issues](https://github.com/yourusername/rhino-client/issues)
+- [Discussions](https://github.com/yourusername/rhino-client/discussions)

package/README.md

@@ -0,0 +1,323 @@
+# @startsoft/lumina
+
+> A comprehensive React library for Laravel backend applications with full CRUD, pagination, soft deletes, and multi-tenant support.
+
+[![npm version](https://badge.fury.io/js/@rhino%2Fclient.svg)](https://www.npmjs.com/package/@startsoft/lumina)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ✨ Features
+
+- 🔐 **Authentication** - Built-in auth hooks with Laravel Sanctum support
+- 🏢 **Multi-tenancy** - Organization-based routing and data scoping
+- 📊 **Complete CRUD** - Index, show, create, update, delete operations
+- 🗑️ **Soft Deletes** - Trash, restore, and force delete support
+- 🔍 **Advanced Querying** - Search, filters, sorting, field selection, pagination
+- 🔗 **Relationships** - Eager loading with includes
+- 🔄 **Nested Operations** - Multi-model transactions
+- 📝 **Audit Trails** - Track changes and history
+- ⚡ **React Query** - Built on TanStack Query for caching and state management
+- 📘 **TypeScript** - Full TypeScript support with type definitions
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @startsoft/lumina
+# or
+yarn add @startsoft/lumina
+# or
+pnpm add @startsoft/lumina
+```
+
+---
+
+## 🚀 Quick Start
+
+```tsx
+import { useModelIndex, useModelStore } from '@startsoft/lumina';
+
+function PostsList() {
+  // Fetch posts with pagination
+  const { data: response, isLoading } = useModelIndex('posts', {
+    page: 1,
+    perPage: 20,
+    search: 'react',
+    includes: ['author'],
+    sort: '-created_at'
+  });
+
+  const posts = response?.data || [];
+  const pagination = response?.pagination;
+
+  // Create new post
+  const createPost = useModelStore('posts');
+
+  const handleCreate = () => {
+    createPost.mutate({
+      title: 'My Post',
+      content: 'Post content'
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <button onClick={handleCreate}>Create Post</button>
+
+      {posts.map(post => (
+        <div key={post.id}>
+          <h3>{post.title}</h3>
+          {post.author && <p>By: {post.author.name}</p>}
+        </div>
+      ))}
+
+      {pagination && (
+        <div>
+          Page {pagination.currentPage} of {pagination.lastPage}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## 📚 Documentation
+
+- **[Getting Started](./docs/getting-started.md)** - Installation and setup
+- **[API Reference](./docs/API.md)** - Complete hook documentation
+- **[Features Guide](./docs/features/)** - Detailed feature explanations
+  - [Pagination](./docs/features/pagination.md)
+  - [Soft Deletes](./docs/features/soft-deletes.md)
+  - [Filtering & Search](./docs/features/filtering.md)
+  - [Relationships](./docs/features/relationships.md)
+  - [Nested Operations](./docs/features/nested-operations.md)
+- **[Examples](./docs/examples/)** - Real-world usage examples
+
+---
+
+## 🎯 Core Hooks
+
+### CRUD Operations
+
+| Hook | Purpose |
+|------|---------|
+| `useModelIndex` | Fetch list of models with pagination, filtering, search |
+| `useModelShow` | Fetch single model by ID |
+| `useModelStore` | Create new model |
+| `useModelUpdate` | Update existing model |
+| `useModelDelete` | Soft delete model |
+
+### Soft Deletes
+
+| Hook | Purpose |
+|------|---------|
+| `useModelTrashed` | Fetch soft-deleted models |
+| `useModelRestore` | Restore soft-deleted model |
+| `useModelForceDelete` | Permanently delete model |
+
+### Advanced Features
+
+| Hook | Purpose |
+|------|---------|
+| `useNestedOperations` | Multi-model transactions |
+| `useModelAudit` | Fetch audit trail for a model |
+
+### Authentication & Organization
+
+| Hook | Purpose |
+|------|---------|
+| `useAuth` | Authentication state and methods |
+| `useOrganization` | Current organization slug |
+| `useOwner` | Organization data |
+| `useOrganizationExists` | Validate organization |
+
+### Invitations
+
+| Hook | Purpose |
+|------|---------|
+| `useInvitations` | List invitations |
+| `useInviteUser` | Create invitation |
+| `useResendInvitation` | Resend invitation |
+| `useCancelInvitation` | Cancel invitation |
+| `useAcceptInvitation` | Accept invitation |
+
+**[View complete API reference →](./docs/API.md)**
+
+---
+
+## 🏗️ Architecture
+
+Built with modern technologies:
+
+- **React 19** - Latest React features and performance
+- **TanStack Query 5** - Powerful data fetching and caching
+- **Axios** - HTTP client with interceptors
+- **TypeScript** - Full type safety
+
+### Design Principles
+
+- **Composable** - Small, focused hooks that work together
+- **Type-Safe** - Full TypeScript support with IntelliSense
+- **Cached** - Automatic caching and background refetching
+- **Optimized** - Only re-renders when data changes
+- **Laravel-First** - Designed specifically for Laravel backends
+
+---
+
+## 💡 Key Features
+
+### Pagination
+
+Automatic pagination metadata extraction from Laravel response headers:
+
+```tsx
+const { data: response } = useModelIndex('posts', {
+  page: 2,
+  perPage: 20
+});
+
+const posts = response?.data || [];
+const pagination = response?.pagination;
+// { currentPage: 2, lastPage: 10, perPage: 20, total: 195 }
+```
+
+### Filtering & Search
+
+Powerful query building with filters and full-text search:
+
+```tsx
+const { data: response } = useModelIndex('posts', {
+  search: 'react hooks',
+  filters: {
+    status: 'published',
+    category: 'tech'
+  },
+  sort: '-created_at'
+});
+```
+
+### Relationships
+
+Eager load related data with includes:
+
+```tsx
+const { data: post } = useModelShow('posts', 123, {
+  includes: ['author', 'comments', 'tags']
+});
+```
+
+### Soft Deletes
+
+Complete soft delete workflow:
+
+```tsx
+const deletePost = useModelDelete('posts');
+const trashedPosts = useModelTrashed('posts');
+const restore = useModelRestore('posts');
+const forceDelete = useModelForceDelete('posts');
+
+// Soft delete
+deletePost.mutate(postId);
+
+// Restore
+restore.mutate(postId);
+
+// Permanently delete
+forceDelete.mutate(postId);
+```
+
+### Nested Operations
+
+Execute multiple operations in a single transaction:
+
+```tsx
+const nestedOps = useNestedOperations();
+
+nestedOps.mutate({
+  operations: [
+    {
+      action: 'create',
+      model: 'blogs',
+      data: { title: 'My Blog' }
+    },
+    {
+      action: 'create',
+      model: 'posts',
+      data: {
+        title: 'First Post',
+        blog_id: '$0.id' // Reference first operation's result
+      }
+    }
+  ]
+});
+```
+
+---
+
+## 🔧 Requirements
+
+- **React:** 18.0.0 or higher
+- **Node.js:** 18.0.0 or higher
+- **Laravel Backend:** with [laravel-global-controller](https://github.com/yourusername/laravel-global-controller) package
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/rhino-client.git
+cd rhino-client
+
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Build library
+npm run build
+
+# Run tests
+npm test
+```
+
+---
+
+## 📄 License
+
+MIT © [Your Name]
+
+See [LICENSE](./LICENSE) for more information.
+
+---
+
+## 🔗 Links
+
+- [Documentation](./docs/)
+- [Changelog](./CHANGELOG.md)
+- [Issues](https://github.com/yourusername/rhino-client/issues)
+- [Laravel Backend Package](https://github.com/yourusername/laravel-global-controller)
+- [npm Package](https://www.npmjs.com/package/@startsoft/lumina)
+
+---
+
+## 🙏 Acknowledgments
+
+Inspired by the [Rhino Framework](https://rhino-framework.com) for Rails. Built to bring the same powerful patterns to Laravel + React applications.
+
+---
+
+<p align="center">
+  Made with ❤️ for the Laravel community
+</p>

package/dist/hooks/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Barrel exports for all hooks in @rhino/client
+ */
+export { useAuth } from './useAuth';
+export { useOrganization } from './useOrganization';
+export { useOwner } from './useOwner';
+export { useOrganizationExists } from './useOrganizationExists';
+export { useModelIndex, useModelShow, useModelStore, useModelUpdate, useModelDelete, } from './useModel';
+export { useModelTrashed, useModelRestore, useModelForceDelete, } from './useModel';
+export { useNestedOperations, useModelAudit, } from './useModel';
+export { useInvitations, useInviteUser, useResendInvitation, useCancelInvitation, useAcceptInvitation, } from './useInvitations';
+export { useToast } from './use-toast';
+export { useModelQuery } from './useModelQuery';

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @startsoft/lumina - Main entry point
+ *
+ * A comprehensive React library for Laravel backend applications with
+ * full CRUD, pagination, soft deletes, and multi-tenant support.
+ */
+export * from './hooks';
+export * from './lib';
+export { AuthProvider, useAuth } from './context/AuthContext';
+export { ThemeProvider, useTheme } from './context/ThemeContext';
+export type { PaginationMeta, ModelQueryOptions, NestedOperation, AuditLog, LoginResult, QueryResponse, InvitationStatus, Invitation, Organization, User, Role, } from './types';