@elevasis/ui 2.31.0 → 2.33.0

package/src/graph/README.md

@@ -1,16 +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.
-
+# 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

@@ -1,23 +1,23 @@
-# 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 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.
+# 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 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

@@ -1,19 +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.
-
+# 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/knowledge/README.md

@@ -1,31 +1,31 @@
-# @elevasis/ui/knowledge
-
-Read-only browser primitives for the Organization Model knowledge graph.
-
-## Surface
-
-| Export                                                                 | Purpose                                                                             |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.             |
-| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication. |
-| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                 |
-| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups. |
-| `KnowledgeSearchBar`                                                   | Client-side search over `_generated/knowledge-search-index.json`.                   |
-| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`. |
-| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                    |
-| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`). |
-| `KNOWLEDGE_BODIES`                                                     | Build-time-compiled MDX components keyed by node id.                                |
-
-## Customization tiers
-
-1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
-2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
-3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
-
-## Codegen
-
-`KNOWLEDGE_BODIES` and the search index are regenerated by `pnpm scaffold:sync` (or `pnpm knowledge:generate` to run only the knowledge step). Source: `canonicalOrganizationModel.knowledge.nodes` from `@repo/elevasis-core`.
-
-The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
-
-Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.
+# @elevasis/ui/knowledge
+
+Read-only browser primitives for the Organization Model knowledge graph.
+
+## Surface
+
+| Export                                                                 | Purpose                                                                             |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.             |
+| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication. |
+| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                 |
+| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups. |
+| `KnowledgeSearchBar`                                                   | Client-side search over `_generated/knowledge-search-index.json`.                   |
+| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`. |
+| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                    |
+| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`). |
+| `KNOWLEDGE_BODIES`                                                     | Build-time-compiled MDX components keyed by node id.                                |
+
+## Customization tiers
+
+1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
+2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
+3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
+
+## Codegen
+
+`KNOWLEDGE_BODIES` and the search index are regenerated by `pnpm scaffold:sync` (or `pnpm knowledge:generate` to run only the knowledge step). Source: `canonicalOrganizationModel.knowledge.nodes` from `@repo/elevasis-core`.
+
+The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
+
+Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.

package/src/organization/README.md

@@ -1,18 +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.
-
+# 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

@@ -1,19 +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.
-
+# 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

@@ -1,32 +1,32 @@
-# Provider
-
-The provider surface composes the shared Elevasis service, feature, appearance, notification, and UI providers.
-
-## Exports
-
-The following are exported from `published.ts`, which is the external consumer surface for `@elevasis/ui/provider`:
-
-- `ElevasisCoreProvider`
-- `ElevasisFeaturesProvider`
-- `useElevasisFeatures`
-- `useOptionalElevasisFeatures`
-- `FeatureShell`
-- `AppearanceProvider`
-- `useAppearance`
-- `ElevasisServiceProvider`
-- `useElevasisServices`
-- `NotificationProvider`
-- `useNotificationAdapter`
-- Related provider and service types
-
-Note: `ElevasisUIProvider` (the Mantine-facing visual layer) is available internally via `@repo/ui` but is NOT exported from the published `@elevasis/ui/provider` subpath. It is only available via the internal `./provider/ui` monorepo subpath.
-
-## Related Published Subpaths
-
-- `./provider` - headless providers (points to `published.ts`; no Mantine dependency)
-- `./provider/ui` - full provider including Mantine-dependent `ElevasisUIProvider` (internal monorepo use; also published for consumers that opt in)
-
-## Notes
-
-- `published.ts` is the external consumer surface for `@elevasis/ui/provider`.
-- `ElevasisUIProvider` is Mantine-dependent and available only via `@repo/ui` internally or `@elevasis/ui/provider/ui`; it is not included in the headless `./provider` published export.
+# Provider
+
+The provider surface composes the shared Elevasis service, system, appearance, notification, and UI providers.
+
+## Exports
+
+The following are exported from `published.ts`, which is the external consumer surface for `@elevasis/ui/provider`:
+
+- `ElevasisCoreProvider`
+- `ElevasisSystemsProvider`
+- `useElevasisSystems`
+- `useOptionalElevasisSystems`
+- `SystemShell`
+- `AppearanceProvider`
+- `useAppearance`
+- `ElevasisServiceProvider`
+- `useElevasisServices`
+- `NotificationProvider`
+- `useNotificationAdapter`
+- Related provider and service types
+
+Note: `ElevasisUIProvider` (the Mantine-facing visual layer) is available internally via `@repo/ui` but is NOT exported from the published `@elevasis/ui/provider` subpath. It is only available via the internal `./provider/ui` monorepo subpath.
+
+## Related Published Subpaths
+
+- `./provider` - headless providers (points to `published.ts`; no Mantine dependency)
+- `./provider/ui` - full provider including Mantine-dependent `ElevasisUIProvider` (internal monorepo use; also published for consumers that opt in)
+
+## Notes
+
+- `published.ts` is the external consumer surface for `@elevasis/ui/provider`.
+- `ElevasisUIProvider` is Mantine-dependent and available only via `@repo/ui` internally or `@elevasis/ui/provider/ui`; it is not included in the headless `./provider` published export.

package/src/router/README.md

@@ -1,18 +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.
-
+# 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

@@ -1,13 +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.
-
+# 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/test-utils/README.md

@@ -1,7 +1,7 @@
-# UI Test Utilities
-
-Published test helpers for consumers that test Elevasis UI composition.
-
-Use `@elevasis/ui/test-utils` for provider-aware React rendering, WorkOS auth mocks, MSW handlers, and test query clients. Use `@elevasis/ui/test-utils/setup` or `@elevasis/ui/test-utils/setup-integration` from Vitest `setupFiles` when a consumer wants the shared browser and auth mocks.
-
-`renderWithProviders`, `renderHookWithProviders`, and `createTestWrapper` include `ApiClientProvider`, `ElevasisServiceProvider`, `QueryClientProvider`, and `MantineProvider` by default. Tests can override `queryClient`, `getAccessToken`, `organizationId`, `isOrganizationReady`, `apiRequest`, and `isServiceReady` per render.
+# UI Test Utilities
+
+Published test helpers for consumers that test Elevasis UI composition.
+
+Use `@elevasis/ui/test-utils` for provider-aware React rendering, WorkOS auth mocks, MSW handlers, and test query clients. Use `@elevasis/ui/test-utils/setup` or `@elevasis/ui/test-utils/setup-integration` from Vitest `setupFiles` when a consumer wants the shared browser and auth mocks.
+
+`renderWithProviders`, `renderHookWithProviders`, and `createTestWrapper` include `ApiClientProvider`, `ElevasisServiceProvider`, `QueryClientProvider`, and `MantineProvider` by default. Tests can override `queryClient`, `getAccessToken`, `organizationId`, `isOrganizationReady`, `apiRequest`, and `isServiceReady` per render.

package/src/theme/README.md

@@ -1,23 +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.
-
+# 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/theme/presets/README.md

@@ -1,19 +1,19 @@
-# Theme Presets
-
-Re-exports the canonical theme-preset SSOT from `@repo/core`. This subpath exists so that consumers can import preset metadata without pulling in the full theme runtime surface.
-
-## Exports
-
-- `THEME_PRESETS` — `as const` tuple of preset names; the single source of truth.
-- `ThemePresetName` — union type derived from `THEME_PRESETS`.
-- `ThemePresetEnum` — Zod enum derived from `THEME_PRESETS`.
-
-## Use When
-
-- You need a Zod-validated preset name (form schemas, API request/response validation).
-- You need the union type for component props or Zustand state.
-- You're adding a new preset and want to ensure it propagates everywhere via the canonical tuple.
-
-## Source Of Truth
-
-`packages/core/src/auth/multi-tenancy/theme-presets.ts`. This subpath is a thin re-export. The `ui → core` dependency stays one-directional; the runtime preset catalog (`presets`, `getPreset`) lives at `@repo/ui/theme` and consumes the names declared in core.
+# Theme Presets
+
+Re-exports the canonical theme-preset SSOT from `@repo/core`. This subpath exists so that consumers can import preset metadata without pulling in the full theme runtime surface.
+
+## Exports
+
+- `THEME_PRESETS` — `as const` tuple of preset names; the single source of truth.
+- `ThemePresetName` — union type derived from `THEME_PRESETS`.
+- `ThemePresetEnum` — Zod enum derived from `THEME_PRESETS`.
+
+## Use When
+
+- You need a Zod-validated preset name (form schemas, API request/response validation).
+- You need the union type for component props or Zustand state.
+- You're adding a new preset and want to ensure it propagates everywhere via the canonical tuple.
+
+## Source Of Truth
+
+`packages/core/src/auth/multi-tenancy/theme-presets.ts`. This subpath is a thin re-export. The `ui → core` dependency stays one-directional; the runtime preset catalog (`presets`, `getPreset`) lives at `@repo/ui/theme` and consumes the names declared in core.

package/src/types/README.md

@@ -1,16 +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.
-
+# 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

@@ -1,18 +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.
-
+# 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

@@ -1,18 +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.
-
+# 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.
+