create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/setup/11-hooks-api.md

@@ -0,0 +1,393 @@
+# Hooks API Reference
+
+**All Kernel Hooks and Their Usage**
+
+---
+
+## Overview
+
+The Lego-One Kernel provides hooks for authentication, authorization, state management, and plugin communication.
+
+---
+
+## Authentication Hooks
+
+### useAuth()
+
+Get current authentication state and auth methods.
+
+**Location:** `host/src/kernel/hooks/useAuth.ts`
+
+**Returns:**
+```typescript
+{
+  user: User | null;
+  token: string | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  login: (email: string, password: string) => Promise<void>;
+  register: (data: RegisterData) => Promise<void>;
+  logout: () => void;
+  updateProfile: (data: UpdateProfileData) => Promise<void>;
+}
+```
+
+**Example:**
+```typescript
+function MyComponent() {
+  const { user, isAuthenticated, logout } = useAuth();
+
+  if (!isAuthenticated) {
+    return <div>Please log in</div>;
+  }
+
+  return (
+    <div>
+      Welcome, {user.name}
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+### useRequireAuth()
+
+Hook that redirects to login if not authenticated.
+
+**Location:** `host/src/kernel/hooks/useRequireAuth.ts`
+
+**Example:**
+```typescript
+function ProtectedPage() {
+  useRequireAuth();
+  // User is guaranteed to be authenticated here
+  return <div>Protected content</div>;
+}
+```
+
+---
+
+## Authorization Hooks
+
+### useCurrentOrganization()
+
+Get and set the current organization context.
+
+**Location:** `host/src/kernel/hooks/useCurrentOrganization.ts`
+
+**Returns:**
+```typescript
+{
+  organization: Organization | null;
+  setCurrentOrganization: (org: Organization | null) => void;
+}
+```
+
+**Example:**
+```typescript
+function OrgSelector() {
+  const { organization, setCurrentOrganization } = useCurrentOrganization();
+
+  return (
+    <select
+      value={organization?.id}
+      onChange={(e) => setCurrentOrganization(/* find org by id */)}
+    >
+      {/* Org options */}
+    </select>
+  );
+}
+```
+
+### useHasPermission()
+
+Check if current user has a specific permission.
+
+**Location:** `host/src/kernel/hooks/useHasPermission.ts`
+
+**Parameters:**
+- `resource` - The resource type (e.g., 'users', 'organizations')
+- `action` - The action type (e.g., 'read', 'write', 'delete')
+
+**Returns:**
+```typescript
+(resource: ResourceType, action: ActionType) => Promise<boolean>
+```
+
+**Example:**
+```typescript
+function DeleteButton({ userId }) {
+  const checkPermission = useHasPermission();
+  const [hasPermission, setHasPermission] = useState(false);
+
+  useEffect(() => {
+    checkPermission('users', 'delete').then(setHasPermission);
+  }, [checkPermission]);
+
+  if (!hasPermission) return null;
+
+  return <button>Delete User</button>;
+}
+```
+
+### useRequirePermission()
+
+Hook that checks permission and returns loading state.
+
+**Location:** `host/src/kernel/hooks/useRequirePermission.ts`
+
+**Parameters:**
+- `resource` - The resource to check
+- `action` - The action to check
+
+**Returns:**
+```typescript
+{
+  hasPermission: boolean;
+  isLoading: boolean;
+}
+```
+
+**Example:**
+```typescript
+function AdminPanel() {
+  const { hasPermission, isLoading } = useRequirePermission('users', 'write');
+
+  if (isLoading) return <div>Loading...</div>;
+  if (!hasPermission) return <div>Access denied</div>;
+
+  return <div>Admin content</div>;
+}
+```
+
+### useUserPermissions()
+
+Get all permissions for the current user in current organization.
+
+**Location:** `host/src/kernel/hooks/useUserPermissions.ts`
+
+**Returns:**
+```typescript
+UseQueryResult<Permission[]>
+```
+
+### useOrganizations()
+
+Get all organizations for the current user.
+
+**Location:** `host/src/kernel/hooks/useOrganizations.ts`
+
+**Returns:**
+```typescript
+UseQueryResult<Organization[]>
+```
+
+---
+
+## State Management Hooks
+
+### useGlobalKernelState()
+
+Access the global kernel Zustand store.
+
+**Location:** `host/src/kernel/shared-state/store.ts`
+
+**Returns:**
+```typescript
+{
+  user: User | null;
+  organization: Organization | null;
+  token: string | null;
+  isAuthenticated: boolean;
+  setUser: (user: User | null) => void;
+  setOrganization: (org: Organization | null) => void;
+  setToken: (token: string | null) => void;
+}
+```
+
+**Example:**
+```typescript
+function MyComponent() {
+  const { user, organization, isAuthenticated } = useGlobalKernelState();
+
+  return (
+    <div>
+      {isAuthenticated && (
+        <p>{user?.name} - {organization?.name}</p>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Data Hooks
+
+### usePocketBase()
+
+Get the PocketBase client instance.
+
+**Location:** `host/src/kernel/providers/PocketBaseProvider.tsx` or `packages/plugins/@lego/plugin-*/src/hooks/usePocketBase.ts`
+
+**Returns:**
+```typescript
+PocketBase | null
+```
+
+**Example:**
+```typescript
+function MyComponent() {
+  const pb = usePocketBase();
+
+  useEffect(() => {
+    if (pb) {
+      // Use PocketBase client
+      pb.collection('todos').getList(1, 20);
+    }
+  }, [pb]);
+}
+```
+
+---
+
+## Channel Hooks
+
+### useToastChannel()
+
+Show toast notifications via the channel bus.
+
+**Location:** `host/src/kernel/channels/useToastChannel.ts`
+
+**Returns:**
+```typescript
+(data: ToastData) => void
+```
+
+**Example:**
+```typescript
+function MyForm() {
+  const showToast = useToastChannel();
+
+  const handleSubmit = async () => {
+    await saveData();
+    showToast({
+      type: 'success',
+      title: 'Saved!',
+      description: 'Your data has been saved',
+    });
+  };
+}
+```
+
+### useChannelBus()
+
+Access the channel bus for custom events.
+
+**Location:** `host/src/kernel/channels/` or plugin-level implementation
+
+**Returns:**
+```typescript
+{
+  publish: (channel: string, message: any) => void;
+  subscribe: (channel: string, callback: (data: any) => void) => () => void;
+}
+```
+
+**Example:**
+```typescript
+function MyComponent() {
+  const { publish, subscribe } = useChannelBus();
+
+  useEffect(() => {
+    const unsubscribe = subscribe('custom:event', (data) => {
+      console.log('Received:', data);
+    });
+    return unsubscribe;
+  }, [subscribe]);
+
+  const handleClick = () => {
+    publish('custom:event', { message: 'Hello!' });
+  };
+}
+```
+
+---
+
+## Plugin Hooks (Window Bridge)
+
+### Accessing Kernel State from Plugins
+
+```typescript
+// In plugin component
+function MyPluginComponent() {
+  const kernelState = window.__LEGO_KERNEL_STATE__;
+
+  return (
+    <div>
+      <p>User: {kernelState?.user?.email}</p>
+      <p>Org: {kernelState?.organization?.name}</p>
+    </div>
+  );
+}
+```
+
+### Subscribing to Events from Plugins
+
+```typescript
+// In plugin component
+useEffect(() => {
+  const channelBus = window.__LEGO_CHANNEL_BUS__;
+  if (!channelBus) return;
+
+  const unsubscribe = channelBus.subscribe('lego:auth', (data) => {
+    console.log('Auth changed:', data);
+  });
+
+  return unsubscribe;
+}, []);
+```
+
+---
+
+## Hook Parameters and Types
+
+### User Type
+
+```typescript
+interface User {
+  id: string;
+  email: string;
+  name?: string;
+  avatar?: string;
+  created: string;
+  updated: string;
+}
+```
+
+### Organization Type
+
+```typescript
+interface Organization {
+  id: string;
+  name: string;
+  slug: string;
+  created: string;
+  updated: string;
+}
+```
+
+### Permission Type
+
+```typescript
+interface Permission {
+  id: string;
+  resource: string;
+  action: string;
+  roleId: string;
+}
+```
+
+---
+
+**Next:** Read [`12-components-api.md`](./12-components-api.md) for UI component reference.