@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/user-states.mdx

@@ -0,0 +1,794 @@
+---
+title: User States
+description: User-specific state storage mechanism for persisting user preferences, configurations, and application settings
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+**User States** provide a key-value storage mechanism for applications to persist user-specific information such as preferences, configurations, and parameters. This enables personalized user experiences that persist across sessions.
+
+## Overview
+
+User States allow applications to store and retrieve user-specific data:
+
+<CardGrid stagger>
+  <Card title="Key-Value Storage" icon="seti:db">
+    Simple key-value pairs scoped to user and application
+  </Card>
+
+  <Card title="Persistent Storage" icon="seti:lock">
+    Data persists across sessions and survives browser refreshes
+  </Card>
+
+  <Card title="Application-Scoped" icon="seti:folder">
+    Values are isolated per application - no cross-app data leakage
+  </Card>
+
+  <Card title="React Hooks API" icon="seti:react">
+    Easy-to-use React hooks for UI applications
+  </Card>
+
+  <Card title="REST API" icon="random">
+    RESTful endpoints for backend services and non-React apps
+  </Card>
+
+  <Card title="Hierarchical Keys" icon="seti:text">
+    Support for namespaced keys using `::` separator
+  </Card>
+</CardGrid>
+
+---
+
+## Common Use Cases
+
+### UI Preferences
+
+Store user interface preferences:
+
+- **Table views and filters**: Column visibility, sort order, pagination size
+- **Layout preferences**: Sidebar collapsed/expanded, theme selection
+- **View modes**: Grid vs list view, compact vs comfortable density
+- **Recently used items**: Last selected entity, recent searches
+
+### Application Configuration
+
+Persist application-specific settings:
+
+- **Default values**: Default currency, language, timezone
+- **Workflow preferences**: Auto-save frequency, confirmation dialogs
+- **Display options**: Date format, number format
+- **Feature flags**: Beta features enabled by user
+
+### User Context
+
+Remember user context between sessions:
+
+- **Last viewed entity**: Resume where user left off
+- **Active filters**: Restore filters from last session
+- **Draft data**: Auto-saved form inputs
+- **Navigation state**: Remember last visited route per application
+
+---
+
+## Data Model
+
+### User State Structure
+
+```typescript
+interface UserState {
+  id: number;
+  user: string;              // User identifier (email/username)
+  application: string;       // Application name
+  name: string;              // Key name (supports :: hierarchy)
+  value: any;                // JSON-serializable value
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+**Example**:
+
+```json
+{
+  "id": 123,
+  "user": "john@acme.com",
+  "application": "crm",
+  "name": "ui::customers::table::columns",
+  "value": ["name", "email", "phone", "status"],
+  "createdAt": "2025-01-01T10:00:00Z",
+  "updatedAt": "2025-01-09T15:30:00Z"
+}
+```
+
+### Hierarchical Keys
+
+Keys support a namespace hierarchy using the `::` separator:
+
+```
+application::feature::component::setting
+
+Examples:
+- ui::menu::collapsed
+- ui::customers::table::pageSize
+- ui::customers::table::filters
+- ui::dashboard::widgets::visible
+- ui::reports::default::currency
+```
+
+**Benefits**:
+- Organized, self-documenting keys
+- Wildcard queries (e.g., `ui::customers::*`)
+- Easy to reason about data structure
+- Avoid key collisions
+
+---
+
+## Client-Side API (React)
+
+For React-based micro-frontends, use the `useUserState` hook:
+
+### Basic Usage
+
+```typescript
+import { useUserState } from '@bluealba-public/pae-ui-react-core';
+
+function MyComponent() {
+  const { value, setValue, loading, error } = useUserState<boolean>(
+    'ui::menu::collapsed'
+  );
+
+  return (
+    <div>
+      <MyMenu collapsed={error ? false : value} />
+      <Checkbox
+        checked={value}
+        onChange={(e) => setValue(e.target.checked)}
+        disabled={loading}
+      />
+      {error && <span>Error loading preference</span>}
+    </div>
+  );
+}
+```
+
+**Hook API**:
+
+```typescript
+function useUserState<T>(key: string): {
+  value: T | null;          // Current value (null if unset or loading)
+  setValue: (value: T) => Promise<void>;  // Update value
+  loading: boolean;         // True while fetching or updating
+  error: Error | null;      // Error if fetch/update failed
+}
+```
+
+### Automatic Context Inference
+
+The hook automatically infers:
+- **User**: From current authenticated user
+- **Application**: From the micro-frontend's application context
+
+No need to manually specify these - the platform handles it!
+
+### Type Safety
+
+Use TypeScript generics for type-safe values:
+
+```typescript
+interface TablePreferences {
+  pageSize: number;
+  sortBy: string;
+  sortOrder: 'asc' | 'desc';
+  visibleColumns: string[];
+}
+
+function CustomersTable() {
+  const { value: prefs, setValue } = useUserState<TablePreferences>(
+    'ui::customers::table::preferences'
+  );
+
+  // prefs is typed as TablePreferences | null
+  const pageSize = prefs?.pageSize ?? 10;
+  const sortBy = prefs?.sortBy ?? 'name';
+
+  const updatePageSize = (newSize: number) => {
+    setValue({
+      ...prefs,
+      pageSize: newSize,
+    });
+  };
+
+  return <Table pageSize={pageSize} onPageSizeChange={updatePageSize} />;
+}
+```
+
+### Loading States
+
+Handle loading and error states:
+
+```typescript
+function UserPreferences() {
+  const { value, setValue, loading, error } = useUserState<boolean>(
+    'ui::darkMode'
+  );
+
+  if (loading) {
+    return <Spinner />;
+  }
+
+  if (error) {
+    return <ErrorMessage>Failed to load preferences</ErrorMessage>;
+  }
+
+  return (
+    <Switch
+      checked={value ?? false}
+      onChange={(checked) => setValue(checked)}
+    />
+  );
+}
+```
+
+### Complex State Example
+
+```typescript
+interface DashboardWidgets {
+  sales: { visible: boolean; position: number; };
+  orders: { visible: boolean; position: number; };
+  customers: { visible: boolean; position: number; };
+  revenue: { visible: boolean; position: number; };
+}
+
+function DashboardCustomizer() {
+  const { value: widgets, setValue } = useUserState<DashboardWidgets>(
+    'ui::dashboard::widgets'
+  );
+
+  const toggleWidget = (widgetName: keyof DashboardWidgets) => {
+    setValue({
+      ...widgets,
+      [widgetName]: {
+        ...widgets[widgetName],
+        visible: !widgets[widgetName].visible,
+      },
+    });
+  };
+
+  const reorderWidget = (widgetName: keyof DashboardWidgets, newPosition: number) => {
+    setValue({
+      ...widgets,
+      [widgetName]: {
+        ...widgets[widgetName],
+        position: newPosition,
+      },
+    });
+  };
+
+  return (
+    <div>
+      {Object.entries(widgets ?? {}).map(([name, config]) => (
+        <WidgetControl
+          key={name}
+          name={name}
+          visible={config.visible}
+          position={config.position}
+          onToggle={() => toggleWidget(name as keyof DashboardWidgets)}
+          onReorder={(pos) => reorderWidget(name as keyof DashboardWidgets, pos)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Server-Side API (REST)
+
+For backend services or non-React frontends, use the REST API:
+
+### Endpoints
+
+<Tabs>
+  <TabItem label="List User States">
+    **GET** `/_/user-states/:application`
+
+    Retrieve all user states for the current user in a specific application.
+
+    **Path Parameters**:
+    - `application` - Application name (required)
+
+    **Authentication**: User is automatically determined from authenticated session
+
+    **Response**:
+    ```json
+    [
+      {
+        "id": 123,
+        "user": "john@acme.com",
+        "application": "crm",
+        "name": "ui::customers::table::columns",
+        "value": ["name", "email", "phone"]
+      },
+      {
+        "id": 124,
+        "user": "john@acme.com",
+        "application": "crm",
+        "name": "ui::customers::table::pageSize",
+        "value": 25
+      }
+    ]
+    ```
+  </TabItem>
+
+  <TabItem label="Get User State">
+    **GET** `/_/user-states/:application/:name`
+
+    Retrieve a specific user state by application and key name.
+
+    **Path Parameters**:
+    - `application` - Application name (required)
+    - `name` - State key name (required)
+
+    **Response**:
+    ```json
+    {
+      "id": 123,
+      "user": "john@acme.com",
+      "application": "crm",
+      "name": "ui::menu::collapsed",
+      "value": true
+    }
+    ```
+
+    **Returns `null` if not found**
+  </TabItem>
+
+  <TabItem label="Create User State">
+    **POST** `/_/user-states/:application/:name`
+
+    Create a new user state.
+
+    **Path Parameters**:
+    - `application` - Application name (required)
+    - `name` - State key name (required)
+
+    **Request Body**:
+    ```json
+    {
+      "value": true
+    }
+    ```
+
+    **Response**:
+    ```json
+    {
+      "id": 123,
+      "user": "john@acme.com",
+      "application": "crm",
+      "name": "ui::menu::collapsed",
+      "value": true
+    }
+    ```
+
+    **Error Responses**:
+    - `409 Conflict` - User state already exists (use PUT to update)
+    - `400 Bad Request` - Value is required
+  </TabItem>
+
+  <TabItem label="Update User State">
+    **PUT** `/_/user-states/:application/:name`
+
+    Update an existing user state.
+
+    **Path Parameters**:
+    - `application` - Application name (required)
+    - `name` - State key name (required)
+
+    **Request Body**:
+    ```json
+    {
+      "value": false
+    }
+    ```
+
+    **Response**:
+    ```json
+    {
+      "id": 123,
+      "user": "john@acme.com",
+      "application": "crm",
+      "name": "ui::menu::collapsed",
+      "value": false
+    }
+    ```
+
+    **Error Responses**:
+    - `404 Not Found` - User state does not exist (use POST to create)
+    - `400 Bad Request` - Value is required
+  </TabItem>
+
+  <TabItem label="Delete User State">
+    **DELETE** `/_/user-states/:application/:name`
+
+    Delete a specific user state.
+
+    **Path Parameters**:
+    - `application` - Application name (required)
+    - `name` - State key name (required)
+
+    **Response**: `204 No Content` (empty response on success)
+
+    **Error Response**:
+    - `404 Not Found` - User state does not exist
+  </TabItem>
+
+  <TabItem label="Delete All States for Application">
+    **DELETE** `/_/user-states/:application`
+
+    Delete all user states for the current user in a specific application.
+
+    **Path Parameters**:
+    - `application` - Application name (required)
+
+    **Response**:
+    ```json
+    {
+      "deletedCount": 12
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Admin: Delete All States for User">
+    **DELETE** `/_/user-states/admin/user/:username`
+
+    Admin endpoint to delete all user states for a specific user across all applications.
+
+    **Path Parameters**:
+    - `username` - Username (required)
+
+    **Response**:
+    ```json
+    {
+      "deletedCount": 45
+    }
+    ```
+
+    **Note**: This is an admin-only endpoint. Requires appropriate admin permissions.
+  </TabItem>
+</Tabs>
+
+### cURL Examples
+
+```bash
+# List all states for an application
+curl -X GET "https://platform.com/_/user-states/crm" \
+  -H "Cookie: auth_token=..."
+
+# Get a specific user state
+curl -X GET "https://platform.com/_/user-states/crm/ui::menu::collapsed" \
+  -H "Cookie: auth_token=..."
+
+# Create a new user state
+curl -X POST "https://platform.com/_/user-states/crm/ui::menu::collapsed" \
+  -H "Content-Type: application/json" \
+  -H "Cookie: auth_token=..." \
+  -d '{
+    "value": true
+  }'
+
+# Update an existing user state
+curl -X PUT "https://platform.com/_/user-states/crm/ui::menu::collapsed" \
+  -H "Content-Type: application/json" \
+  -H "Cookie: auth_token=..." \
+  -d '{
+    "value": false
+  }'
+
+# Delete a user state
+curl -X DELETE "https://platform.com/_/user-states/crm/ui::menu::collapsed" \
+  -H "Cookie: auth_token=..."
+
+# Delete all states for an application
+curl -X DELETE "https://platform.com/_/user-states/crm" \
+  -H "Cookie: auth_token=..."
+
+# Admin: Delete all states for a user
+curl -X DELETE "https://platform.com/_/user-states/admin/user/john@acme.com" \
+  -H "Cookie: auth_token=..."
+```
+
+---
+
+## Advanced Patterns
+
+### Typed State Blueprint (Future Enhancement)
+
+For large applications with many user states, a typed blueprint approach is planned:
+
+```typescript
+// Define complete application user state schema
+interface MyAppUserStateSchema {
+  'ui': {
+    'menu': {
+      'collapsed': boolean;
+    };
+    'customers': {
+      'table': {
+        'columns': string[];
+        'pageSize': number;
+        'filters': {
+          field: string;
+          operator: string;
+          value: any;
+        }[];
+      };
+    };
+  };
+}
+
+// Create typed blueprint
+const MyAppUserState = createUserStateBlueprint<MyAppUserStateSchema>();
+
+// Use with type safety
+function Component() {
+  const { value, setValue } = MyAppUserState.useStateFor('ui::customers::table::filters');
+  // value is typed as the filter array
+}
+```
+
+<Aside type="note" title="Future Feature">
+  The typed blueprint API is planned for a future release and is not yet implemented.
+</Aside>
+
+### Filtering States
+
+Retrieve all states for an application and filter them client-side:
+
+```bash
+# Get all states for an application
+GET /_/user-states/crm
+
+# Then filter the results in your code
+const allStates = await fetch('/_/user-states/crm');
+const tableStates = allStates.filter(state =>
+  state.name.includes('::table::')
+);
+```
+
+### Default Values
+
+Always provide sensible defaults:
+
+```typescript
+function Component() {
+  const { value } = useUserState<number>('ui::table::pageSize');
+
+  // Use default if value is null (not set)
+  const pageSize = value ?? 10;
+
+  return <Table pageSize={pageSize} />;
+}
+```
+
+### Optimistic Updates
+
+Update UI immediately, sync in background:
+
+```typescript
+function Component() {
+  const { value, setValue } = useUserState<boolean>('ui::menu::collapsed');
+  const [localValue, setLocalValue] = useState(value);
+
+  const toggle = async () => {
+    const newValue = !localValue;
+    setLocalValue(newValue);  // Update UI immediately
+    await setValue(newValue);  // Sync to server
+  };
+
+  return <Menu collapsed={localValue} onToggle={toggle} />;
+}
+```
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Use Hierarchical Keys" icon="seti:text">
+    Organize keys with `::` separator for clarity and maintainability
+  </Card>
+
+  <Card title="Provide Defaults" icon="approve-check">
+    Always handle null values with sensible defaults
+  </Card>
+
+  <Card title="Type Your Values" icon="seti:typescript">
+    Use TypeScript generics for type safety
+  </Card>
+
+  <Card title="Scope Appropriately" icon="seti:folder">
+    Use application-specific keys to avoid conflicts
+  </Card>
+
+  <Card title="Handle Errors Gracefully" icon="warning">
+    Don't break UX if user state fetch fails
+  </Card>
+
+  <Card title="Document State Keys" icon="document">
+    Maintain documentation of all user state keys used by your app
+  </Card>
+</CardGrid>
+
+---
+
+## Security Considerations
+
+<Aside type="caution" title="Security Best Practices">
+  - **Never store sensitive data**: Passwords, API keys, tokens should NOT be stored in user states
+  - **Validate on server**: Don't trust user state values blindly - validate them
+  - **Respect tenant boundaries**: User states are tenant-scoped, maintain this isolation
+  - **Size limits**: Avoid storing large objects - user states are for configuration, not data storage
+  - **Rate limiting**: Be mindful of update frequency to avoid overwhelming the API
+</Aside>
+
+---
+
+## Performance Optimization
+
+### Batch Queries
+
+When loading multiple states, fetch in parallel:
+
+```typescript
+function Dashboard() {
+  const widgets = useUserState<WidgetConfig>('ui::dashboard::widgets');
+  const layout = useUserState<LayoutConfig>('ui::dashboard::layout');
+  const theme = useUserState<ThemeConfig>('ui::dashboard::theme');
+
+  // All three queries execute in parallel
+  if (widgets.loading || layout.loading || theme.loading) {
+    return <Loading />;
+  }
+
+  return <DashboardView widgets={widgets.value} layout={layout.value} theme={theme.value} />;
+}
+```
+
+### Debounce Updates
+
+For frequently changing values, debounce updates:
+
+```typescript
+import { useDebouncedCallback } from 'use-debounce';
+
+function SearchInput() {
+  const { value, setValue } = useUserState<string>('ui::search::lastQuery');
+  const [localValue, setLocalValue] = useState(value ?? '');
+
+  const debouncedSave = useDebouncedCallback((newValue: string) => {
+    setValue(newValue);
+  }, 1000);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = e.target.value;
+    setLocalValue(newValue);
+    debouncedSave(newValue);
+  };
+
+  return <input value={localValue} onChange={handleChange} />;
+}
+```
+
+### Memoization
+
+Memoize expensive computations based on user state:
+
+```typescript
+function DataTable() {
+  const { value: columns } = useUserState<string[]>('ui::table::columns');
+
+  const processedData = useMemo(() => {
+    if (!columns) return [];
+    return data.map(row =>
+      Object.fromEntries(
+        Object.entries(row).filter(([key]) => columns.includes(key))
+      )
+    );
+  }, [data, columns]);
+
+  return <Table data={processedData} />;
+}
+```
+
+---
+
+## Future Enhancements
+
+Planned features for future releases:
+
+### Shared States
+
+Allow users to share state with other users or groups:
+
+- **Shared views**: Share table configurations with team members
+- **Team preferences**: Group-level defaults
+- **Template states**: Pre-configured states for new users
+
+### Admin UI
+
+Administrative interface for managing user states:
+
+- **Global user states view**: See all states across all users
+- **User-specific view**: View and edit states for a specific user
+- **Bulk operations**: Delete or update multiple states at once
+- **Analytics**: Most common preferences, usage patterns
+
+### State Migrations
+
+Version and migrate user state schemas:
+
+- **Data versioning**: Track schema version with state data
+- **Automatic migrations**: Migrate old state formats to new schemas
+- **Migration hooks**: Application-defined migration logic
+- **Rollback support**: Safely rollback breaking changes
+
+### State Synchronization
+
+Real-time synchronization across devices:
+
+- **WebSocket updates**: Push state changes to all user sessions
+- **Conflict resolution**: Handle concurrent updates gracefully
+- **Offline support**: Queue updates when offline, sync when reconnected
+
+---
+
+## Troubleshooting
+
+### State Not Persisting
+
+**Check**:
+1. User is authenticated
+2. Application context is set correctly
+3. No network errors (check browser console)
+4. API endpoints are accessible
+
+**Debug**:
+```typescript
+const { value, setValue, error } = useUserState('my::key');
+
+useEffect(() => {
+  console.log('User state:', { value, error });
+}, [value, error]);
+```
+
+### State Not Loading
+
+**Possible Causes**:
+- User state never created (first time user)
+- Wrong key name
+- Application context mismatch
+
+**Solution**: Always provide defaults
+```typescript
+const { value } = useUserState<boolean>('ui::menu::collapsed');
+const collapsed = value ?? false;  // Default to false
+```
+
+### Type Errors
+
+**Cause**: Mismatch between stored value type and TypeScript type.
+
+**Solution**: Validate and transform stored values
+```typescript
+const { value } = useUserState<number>('ui::pageSize');
+const pageSize = typeof value === 'number' && value > 0 ? value : 10;
+```
+
+---
+
+## Next Steps
+
+- **[API Explorer](/_/docs/architecture/api-explorer/)** - Testing user state API endpoints
+- **[Shell Architecture](/_/docs/architecture/shell/)** - Using user states for Shell customization
+- **[Getting Started with UI Development](/_/docs/development/ui-development/)** - Building UIs that use user states