`@prox-os/workspace-ui`

@prox-os/workspace-ui provides OS-native workspace presentation primitives for Prox OS. It models personal homes, team workspaces, community spaces, creator spaces, developer workspaces, and Founder Suite workspaces without owning routing, membership lifecycle, billing, permission enforcement, or backend persistence.

Why Prox OS Needs It

Prox OS is a browser-based OS shell where apps, files, AI sessions, search scopes, notifications, collaboration threads, security reviews, and future activity feeds need a shared workspace context. A normal SaaS admin dashboard is too narrow for this surface. The package gives apps and the shell a common set of serializable workspace view models and reusable React primitives.

Package Scope

• Workspace, space, member, role, invite, resource, project, milestone, settings, onboarding, integration, stats, and event contracts.
• Helpers for labels, initials, navigation, member filtering, resource filtering, stats summaries, onboarding progress, project progress, and workspace context creation.
• Adapter examples for actions, app manifests, files, search, notifications, collaboration, security UI, AI UI, command metadata, generic resources, and future activity drafts.
• Mock data for personal, team, community, creator, founder, and developer workspace scenarios.
• React primitives for switchers, cards, headers, sidebars, dashboards, spaces, resources, projects, milestones, members, invite previews, settings summaries, onboarding, integrations, and states.

Non-Goals

• No workspace backend, membership service, invite delivery, organization management, billing, seat management, SSO, or auth provider.
• No RBAC/ABAC enforcement. Security-heavy permission surfaces belong to @prox-os/security-ui.
• No file manager, search engine, notification center, collaboration timeline, AI runtime, or activity timeline.
• No OS routing rewrite and no private imports from apps/os-shell.
• No project management engine, kanban board, CRM, knowledge base clone, or realtime provider.

Core Concepts

• Workspace: A top-level OS context such as a personal home, team workspace, community space, creator space, developer workspace, or Founder Suite workspace.
• Space: A workspace section such as home, docs, files, apps, AI, community, settings, or a custom project area.
• Member: A user, guest, team, agent, integration, or system participant represented for UI and adapters.
• Role: A presentation role such as owner, admin, editor, reviewer, viewer, guest, or agent. It is metadata, not enforcement.
• Invite: A mock invite view model. Delivery and acceptance belong to a future workspace backend.
• Resource: A workspace-owned app, document, file, project, milestone, AI session, security review, notification feed, collaboration thread, activity feed, external URL, or system entry.
• Navigation item: A serializable sidebar or switcher item derived from workspace spaces and resources.
• Project / milestone: Lightweight summaries for workspace dashboards, not a full project management system.
• Settings summary: Display-only visibility, default role, security mode, AI, public profile, and notification settings.
• Onboarding checklist: Mock checklist state for workspace setup.
• Integration: Display-only provider state for GitHub, Cloudflare, Neon, Storybook, Docs, API, AI provider, analytics, or custom integrations.
• Workspace context: A runtime-agnostic container for current workspace, current space, workspace list, members, resources, and stats.

Core API

Key types include OsWorkspace, OsSpace, OsWorkspaceRole, OsWorkspaceMember, OsWorkspaceInvite, OsWorkspaceResource, OsWorkspaceNavigationItem, OsWorkspaceProject, OsWorkspaceMilestone, OsWorkspaceSettingsSummary, OsWorkspaceOnboardingItem, OsWorkspaceIntegration, OsWorkspaceStats, OsWorkspaceContextValue, and OsWorkspaceUiEvent.

Key helpers include getWorkspaceKindLabel, getWorkspaceDisplayName, getWorkspaceRoute, getPrimaryWorkspaceRole, isWorkspaceOwner, filterWorkspaceMembers, filterWorkspaceResources, sortWorkspaceResources, groupResourcesByKind, getWorkspaceNavigationItems, getWorkspaceStatsSummary, getOnboardingProgress, getProjectProgress, createWorkspaceResource, and createWorkspaceContext.

Adapter examples include workspaceToOpenAction, workspaceResourceToOpenAction, appManifestToWorkspaceResource, fileNodeToWorkspaceResource, workspaceToSearchDocument, workspaceEventToNotificationDraft, workspaceMemberToParticipant, workspaceMemberToSecurityPrincipal, workspaceResourceToAiContextSource, workspaceEventToActivityDraft, workspaceToCommand, and genericResourceToWorkspaceResource.

React Primitives

• Identity and status: OsWorkspaceBadge, OsWorkspaceAvatar, OsWorkspaceStatusBadge, OsWorkspaceRoleBadge.
• Switcher and layout: OsWorkspaceSwitcher, OsWorkspaceCard, OsWorkspaceHeader, OsWorkspaceSidebar, OsWorkspaceDashboard, OsWorkspaceSection, OsSpaceTabs.
• Resources and work: OsWorkspaceResourceCard, OsWorkspaceResourceGrid, OsWorkspaceProjectCard, OsWorkspaceMilestoneList, OsWorkspaceStatsGrid.
• Members and invites: OsWorkspaceMemberAvatar, OsWorkspaceMemberList, OsWorkspaceInvitePanel.
• Settings and setup: OsWorkspaceSettingsSummaryCard, OsWorkspaceOnboardingChecklist, OsWorkspaceIntegrationCard.
• States: OsWorkspaceEmptyState, OsWorkspaceLoadingState, OsWorkspaceErrorState.

The data type is named OsWorkspaceSettingsSummary, so the React component uses OsWorkspaceSettingsSummaryCard to avoid an exported name collision.

Mock Data

The package exports mock workspaces, spaces, roles, members, invites, resources, projects, milestones, settings, onboarding items, integrations, stats, creator spaces, and creator resources. The mock set covers:

• esmadrider Home personal workspace.
• Prox OS Core Team team workspace.
• Founder Suite founder workspace.
• Developer Lab developer workspace.
• Community Garden community workspace.
• esmadrider Creator Space creator workspace.

Storybook Examples

UI Workshop stories live under Workspace UI/* and cover overview, switcher, cards/header/sidebar, dashboard, spaces/resources, projects/milestones, members/roles/invites, settings/onboarding, integrations, personal/team/community/creator workspaces, founder/developer workspaces, and cross-package adapters.

Integrations

• @prox-os/actions: workspace UI emits action intents for switching workspaces, opening spaces/resources, inviting members, opening settings, and connecting integrations. It does not execute them.
• @prox-os/security-ui: workspace roles, members, and resources can map to security principals, resources, and permission-set view models. Enforcement belongs elsewhere.
• @prox-os/files: files and folders can become workspace resources. File browsing and previews remain in @prox-os/files.
• @prox-os/search: workspaces, members, resources, and projects can become searchable documents. Search UI and providers remain in @prox-os/search.
• @prox-os/notifications: workspace events can become notification drafts. Toasts, centers, and preferences remain in @prox-os/notifications.
• @prox-os/collaboration: members can become participants and resources can become collaboration resource refs. Threads and reviews remain in @prox-os/collaboration.
• @prox-os/ai-ui: workspaces, projects, and resources can become AI context sources. AI sessions, tool calls, approvals, and runtime belong elsewhere.
• Future @prox-os/activity: workspace events can become activity drafts, but timeline rendering is not part of this package.

Roadmap

Phase 1

• TypeScript contracts.
• Mock workspaces, spaces, members, roles, resources, projects, milestones, settings, onboarding, integrations, and stats.
• Workspace switcher, dashboard, resource, member, project, settings, onboarding, and integration UI primitives.
• Helpers, adapters, Storybook examples, and docs.
• No backend workspace service, invite delivery, billing, permission enforcement, or OS routing rewrite.

Phase 2

• OsWorkspaceProvider and OsWorkspaceContextProvider boundaries.
• Mock provider and local state provider.
• Current workspace persistence adapter.
• Workspace resource registry adapter.
• Mock member/invite state adapter.
• Workspace settings form integration.

Phase 3

• OS top bar workspace switcher.
• App/window/resource-level workspace context injection.
• Command palette workspace switch/search/open integration.
• Search, notifications, security, AI, collaboration, and activity integration.
• Workspace-scoped app registry and route handoff.

Phase 4

• Workspace backend API.
• Membership and invite lifecycle.
• Workspace roles and permissions provider.
• Billing and plan provider.
• Workspace notification routing.
• Workspace search index routing.
• Per-workspace AI and security policies.

Phase 5

• Creator app/resource surfaces for /@creator/apps/....
• Public and community workspace profiles.
• Community app/resource curation.
• Moderation, security, and trust integration.
• Creator-owned app spaces and datasets.

Acceptance Checklist

• Package is recognized as @prox-os/workspace-ui.
• Public entry exports types, helpers, adapters, mock data, and components.
• Local helpers operate on mock data without a backend.
• Storybook examples render in @prox-os/ui-workshop.
• Docs define the package boundary and explain Phase 1 versus later provider work.
• No private shell imports, billing SDKs, auth SDKs, project management engines, or realtime backends are introduced.