@elevasis/ui 2.4.0 → 2.5.0

package/src/api/README.md

@@ -0,0 +1,18 @@
+# API
+
+The API surface provides the HTTP client provider, the context hook, and the API config types.
+
+## Exports
+
+- `ApiClientProvider`
+- `useApiClientContext`
+- `useApiClient`
+- `ApiClientContextValue`
+- `ApiClientProviderProps`
+- `ApiErrorDetails`
+
+## Use When
+
+- You need a shared API request client at the app root.
+- You want org-aware request access through `useApiClient`.
+

package/src/auth/README.md

@@ -0,0 +1,18 @@
+# Auth
+
+The auth surface is the published authentication entry point for UI shells.
+
+## Exports
+
+- `AuthProvider`
+- `useAuthContext`
+- `useStableAccessToken`
+- `useSessionCheck`
+- `ProtectedRoute`
+- `AdminGuard`
+
+## Use When
+
+- You need auth state, access tokens, or session lifecycle checks.
+- You need route-level guards for protected or admin-only UI.
+

package/src/components/README.md

@@ -0,0 +1,24 @@
+# Components
+
+This barrel groups the shared visual and domain UI surfaces that remain part of the published component layer.
+
+## What It Covers
+
+- Acquisition and CRM UI primitives
+- Navigation, breadcrumbs, tables, forms, modals, and display components
+- Charts, monitoring widgets, notifications, and error states
+- Layout shells, backgrounds, and sidebar primitives
+- Typeform, rich text, content, and resource-definition helpers
+- Operations UI surfaces that are still shared at the component layer
+
+## Related Subpaths
+
+- `./components/navigation`
+- `./components/chat`
+- `./layout`
+- `./charts`
+
+## Notes
+
+- The component layer is broad by design, but feature-oriented application shells should still prefer `./features/*` when a dedicated feature surface exists.
+

package/src/execution/README.md

@@ -0,0 +1,16 @@
+# Execution
+
+The execution surface contains headless helpers for execution timelines, workflow layouts, and execution-specific data shaping.
+
+## Exports
+
+- Hooks under `./hooks`
+- Utilities under `./utils`
+- Execution types under `./types`
+- Shared execution constants
+
+## Use When
+
+- You need execution timeline or workflow graph helpers without pulling in visual shells.
+- You need shared execution math or formatting utilities.
+

package/src/features/README.md

@@ -0,0 +1,28 @@
+# Features
+
+Feature subpaths package complete shell-level UI flows for downstream apps.
+
+## Published Feature Surfaces
+
+- `./features/auth`
+- `./features/crm`
+- `./features/dashboard`
+- `./features/delivery`
+- `./features/lead-gen`
+- `./features/operations`
+- `./features/monitoring`
+- `./features/seo`
+- `./features/settings`
+
+## What They Contain
+
+- Route shells and page-level components
+- Sidebars and feature-specific navigation
+- Feature manifests for registry consumers
+- Feature-specific hooks and shared constants
+
+## Notes
+
+- These surfaces are meant for app composition, not for low-level design-system primitives.
+- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.
+

package/src/graph/README.md

@@ -0,0 +1,16 @@
+# Graph
+
+The graph surface is headless. It provides hooks, types, constants, and utilities for ReactFlow-based graph behavior.
+
+## Exports
+
+- Graph constants
+- Graph types
+- Graph hooks
+- Graph utilities
+
+## Notes
+
+- Visual graph components moved out of this package surface.
+- Use this subpath when you need graph behavior without the visual shell.
+

package/src/hooks/README.md

@@ -0,0 +1,24 @@
+# Hooks
+
+The hooks barrel is the published headless hook surface for the UI package.
+
+## Grouped Areas
+
+- Execution and workflow hooks
+- Scheduling hooks
+- Monitoring, observability, and notification hooks
+- Session and SSE hooks
+- Operations hooks, including command-view and knowledge-base helpers
+- Feature access, table state, and service helpers
+- Acquisition and delivery hooks
+
+## Published Subpaths
+
+- `./hooks`
+- `./hooks/delivery`
+- `./hooks/operations/command-view/utils/transformCommandViewData`
+
+## Notes
+
+- This barrel is intentionally headless. It should not pull in the visual component layer.
+

package/src/initialization/README.md

@@ -0,0 +1,19 @@
+# Initialization
+
+The initialization surface coordinates org-aware app startup.
+
+## Exports
+
+- `InitializationProvider`
+- `useInitialization`
+- `InitializationContext`
+- `createUseAppInitialization`
+- `InitializationError`
+- `AppInitializationState`
+- `SupabaseUserProfile` type re-export
+
+## Use When
+
+- You need zero-config app bootstrap inside an organization-aware provider tree.
+- You still need the deprecated factory pattern for older consumers.
+

package/src/organization/README.md

@@ -0,0 +1,18 @@
+# Organization
+
+The organization surface manages multi-tenancy state and the related UI controls.
+
+## Exports
+
+- `OrganizationProvider`
+- `OrganizationContext`
+- `useOrganization`
+- `OrganizationSwitcher`
+- Store types and the legacy slice creator
+- Deprecated hook factories for older consumers
+
+## Notes
+
+- Prefer the provider and context exports for new code.
+- Legacy Zustand-based helpers remain exported for migration compatibility.
+

package/src/profile/README.md

@@ -0,0 +1,19 @@
+# Profile
+
+The profile surface manages the user profile context and profile-backed helpers.
+
+## Exports
+
+- `ProfileProvider`
+- `useProfile`
+- `ProfileContextValue`
+- `useUserProfile`
+- `UseUserProfileReturn`
+- `UserProfileService`
+- `SupabaseUserProfile` type re-export
+
+## Use When
+
+- You need a shared user profile context.
+- You need a standalone profile service or hook for sync and access.
+

package/src/provider/README.md

@@ -0,0 +1,31 @@
+# Provider
+
+The provider surface composes the shared Elevasis service, feature, appearance, notification, and UI providers.
+
+## Exports
+
+- `ElevasisCoreProvider`
+- `ElevasisFeaturesProvider`
+- `useElevasisFeatures`
+- `useOptionalElevasisFeatures`
+- `FeatureShell`
+- `AppearanceProvider`
+- `useAppearance`
+- `ElevasisServiceProvider`
+- `useElevasisServices`
+- `NotificationProvider`
+- `useNotificationAdapter`
+- `ElevasisUIProvider`
+- Related provider and service types
+
+## Related Published Subpaths
+
+- `./provider`
+- `./provider/ui`
+- `./provider/ElevasisServiceContext`
+
+## Notes
+
+- `published.ts` is the external consumer surface.
+- `ElevasisUIProvider` is the Mantine-facing visual layer; `ElevasisCoreProvider` and `ElevasisFeaturesProvider` handle the platform shell.
+

package/src/router/README.md

@@ -0,0 +1,18 @@
+# Router
+
+The router surface provides the shared TanStack Router bridge and router context helpers.
+
+## Exports
+
+- `RouterProvider`
+- `useRouterContext`
+- `RouterAdapter`
+- `LinkProps`
+- `TanStackRouterBridge`
+- `ScrollToTop`
+
+## Use When
+
+- You need the shared routing abstraction for Elevasis apps.
+- You need a small adapter layer around TanStack Router in a consuming app.
+

package/src/sse/README.md

@@ -0,0 +1,13 @@
+# SSE
+
+The SSE surface provides connection management and token-refresh helpers for server-sent events.
+
+## Exports
+
+- `SSEConnectionManager`
+- `fetchEventSourceWithTokenRefresh`
+
+## Use When
+
+- You need a shared SSE client with auth-aware reconnect behavior.
+

package/src/theme/README.md

@@ -0,0 +1,23 @@
+# Theme
+
+The theme surface provides the preset system, CSS variable bridge, and Mantine theme integration.
+
+## Exports
+
+- `getPreset`
+- `generateShades`
+- `presets`
+- Theme preset types
+- `createCssVariablesResolver`
+- `TOKEN_VAR_MAP`
+- `mantineThemeOverride`
+- `componentThemes`
+- `PresetsProvider`
+- `usePresetsContext`
+- `useAvailablePresets`
+
+## Use When
+
+- You need to build or customize the Elevasis visual theme.
+- You need access to the shared preset registry or CSS variable mapping.
+

package/src/types/README.md

@@ -0,0 +1,16 @@
+# Types
+
+The types surface re-exports the shared platform types that UI consumers need without a direct `@repo/core` dependency.
+
+## Exports
+
+- Execution and resource types
+- Command queue and scheduling types
+- Monitoring, observability, and notification types
+- Session, feature-access, and webhook types
+- Multi-tenancy, deployment, and CRM acquisition types
+
+## Notes
+
+- This is a type-only bridge. It should stay aligned with the current platform contracts.
+

package/src/utils/README.md

@@ -0,0 +1,18 @@
+# Utils
+
+The utils surface groups shared date, formatting, validation, error, and resource helper functions.
+
+## Exports
+
+- Date formatting helpers
+- Relative time helpers
+- Email validation
+- Error helpers
+- Resource icon helpers
+- Shared constants
+- Warning suppression helpers
+
+## Use When
+
+- You need lightweight shared helpers that do not belong in a feature barrel.
+

package/src/zustand/README.md

@@ -0,0 +1,18 @@
+# Zustand
+
+The Zustand surface exposes the shared slice creators used by the UI package.
+
+## Exports
+
+- `createSSESlice`
+- `resetSSEState`
+- `createThemeSlice`
+- `resetThemeState`
+- `createTimeRangeSlice`
+- `resetTimeRangeState`
+- Slice state and configuration types
+
+## Use When
+
+- You need the shared state slices used by the UI package internals or a compatible consumer.
+