@streamoid/settings 0.3.8 → 0.4.0

package/README.md

@@ -1,6 +1,7 @@
 # @streamoid/settings
 
-Shared Settings module (Account, Workspace, Team, Billing, API Keys, Referral).
+Shared Settings module (Account, Workspace, Organization, Billing, API Keys,
+Referral).
 The host application provides auth, workspace, API, navigation, toast, and
 image-upload implementations through a single **adapter** object — the package
 contains no host-specific code.
@@ -99,6 +100,37 @@ Modals added to this package should call `useOverlayOpen(open, onClose)` at the
 top of the component. That is what registers them in the stack; skip it and
 Escape will close the whole panel out from under the modal.
 
+## Navigation is scope-first (0.4.0)
+
+Destinations are grouped by *whose* settings they are. `workspace/*` tabs act
+on the workspace you are currently in; `organization/*` tabs act on the org
+above it:
+
+| Group | Tabs | URL |
+|---|---|---|
+| — | `profile` | `/account` |
+| Workspace *(named)* | `workspace`, `workspaceMembers`, `workspaceList` | `/workspace/general`, `/workspace/members`, `/workspace/all` |
+| Organization *(named)* | `organization`, `organizationWorkspaces`, `organizationDomains` | `/organization/people`, `/organization/workspaces`, `/organization/domains` |
+| — | `billing`, `apikey` | `/billing`, `/api-keys` |
+
+The group headings carry the entity's own name, so no leaf label repeats the
+word "Workspace" or "Organization" — and "Team", which named a workspace's
+member list without saying which workspace, is gone.
+
+**Host routing.** Scoped slugs have two segments, so a host matching
+`/settings/:tab` needs a second route for `/settings/:tab/:sub`.
+`resolveSettingsTabFromPath` prefers the two-segment match and still resolves
+the pre-0.4 slugs `team`, `workspace` and `organization`, so old links keep
+working.
+
+**Organizations are optional.** When `organization.current` is `null` the whole
+group collapses to one `Organization` row leading to the create/join screen,
+rather than a heading with no name and three empty pages under it.
+
+**Breaking:** the `"team"` member of `SettingsTab` is now `"workspaceMembers"`,
+and `WorkspaceTab` is renamed `WorkspaceListTab` (the old name stays as a
+deprecated alias).
+
 ## Explaining the tabs
 
 Every sub-nav destination carries a hover/focus tooltip sourced from the

package/dist/index.d.mts

@@ -8,13 +8,49 @@ import react__default, { SVGProps, ReactNode } from 'react';
  * resolved tab into <SettingsContent activeTab={...} />. These helpers exist
  * so consumers don't have to re-implement tab/URL conversion if they don't
  * want to.
+ *
+ * ## Scope-first navigation
+ *
+ * Destinations are grouped by *whose* settings they are, not by feature. The
+ * data model is Organization → Workspaces → Members, and the nav now says so:
+ * `workspace/*` tabs act on one workspace, `organization/*` tabs act on the
+ * org above it. The old flat trio — Workspace / Team / Organization — read as
+ * three peers and left "Team" scoped to nothing the user could see.
+ *
+ * Pre-0.4 URLs (`/settings/team`, `/settings/workspace`, `/settings/organization`)
+ * still resolve, so existing links and bookmarks keep working.
  */
-type SettingsTab = "profile" | "workspace" | "referral" | "team" | "organization" | "billing" | "apikey";
-/** Internal tab id → URL slug. */
+type SettingsTab = "profile"
+/** Workspace › General — name, image, org affiliation, leave/delete. */
+ | "workspace"
+/** Workspace › Members — was the top-level "Team" tab. */
+ | "workspaceMembers"
+/** Workspace › All workspaces — the switch/create list. */
+ | "workspaceList"
+/** Organization › People. */
+ | "organization"
+/** Organization › Workspaces. */
+ | "organizationWorkspaces"
+/** Organization › Domains & join requests. */
+ | "organizationDomains" | "referral" | "billing" | "apikey";
+/** Which entity a tab acts on. Drives the nav grouping and the breadcrumb. */
+type SettingsScope = "account" | "workspace" | "organization" | "global";
+declare const TAB_SCOPE: Record<SettingsTab, SettingsScope>;
+/** Fallback scope names, used before the entity's real name has loaded. */
+declare const SCOPE_LABELS: Record<SettingsScope, string>;
+/** Internal tab id → URL slug. Scoped tabs get a two-segment slug. */
 declare const TAB_TO_URL: Record<SettingsTab, string>;
-/** URL slug → internal tab id. */
+/**
+ * URL slug → internal tab id. Two-segment slugs are matched first by
+ * `resolveSettingsTabFromPath`, so the bare `workspace` / `organization`
+ * entries below only catch pre-0.4 links.
+ */
 declare const URL_TO_TAB: Record<string, SettingsTab>;
-/** Human-readable label for each tab (used for breadcrumbs etc.). */
+/**
+ * Human-readable label for each tab. These are *leaf* labels — the scope they
+ * belong to supplies the other half ("Acme Retail › Members"), so no label
+ * needs to repeat the word "Workspace" or "Organization".
+ */
 declare const TAB_LABELS: Record<SettingsTab, string>;
 /**
  * One-line explanation of what each destination is for, shown on hover over the
@@ -24,10 +60,15 @@ declare const TAB_LABELS: Record<SettingsTab, string>;
  */
 declare const TAB_DESCRIPTIONS: Record<SettingsTab, string>;
 /**
- * Resolve a `SettingsTab` from a URL pathname. Looks for the last segment that
- * matches a known slug; falls back to `"profile"` (the default Account tab).
+ * Resolve a `SettingsTab` from a URL pathname. Two-segment slugs
+ * (`workspace/members`) win over single ones, so `/settings/workspace/members`
+ * resolves to the member list rather than to the workspace's General tab.
+ * Falls back to `"profile"` (the default Account tab).
  *
- * Example: `/settings/billing` → `"billing"`.
+ * Examples:
+ *   `/settings/billing`          → `"billing"`
+ *   `/settings/workspace/members`→ `"workspaceMembers"`
+ *   `/settings/team`             → `"workspaceMembers"` (legacy)
  */
 declare function resolveSettingsTabFromPath(path: string): SettingsTab;
 
@@ -744,7 +785,17 @@ type WorkspaceInfo = SettingsWorkspaceListItem & {
     ownerEmail?: string;
 };
 declare function ProfileTab(): react.JSX.Element;
-declare function WorkspaceTab({ workspaces, loading, onCreateClick: _onCreateClick, onEditClick, onSwitchClick, onLeaveClick, }: {
+/**
+ * Workspace › All workspaces — every workspace you belong to, for switching
+ * between them and starting new ones.
+ *
+ * This was the whole of the old "Workspace" tab, which is why that tab never
+ * looked like settings: it is a picker. It keeps the per-row Settings action
+ * (opening `WorkspaceModal`) because from here you may well be editing a
+ * workspace you are not currently inside — the current one has its own
+ * General page.
+ */
+declare function WorkspaceListTab({ workspaces, loading, onCreateClick: _onCreateClick, onEditClick, onSwitchClick, onLeaveClick, }: {
     workspaces: WorkspaceInfo[];
     loading: boolean;
     onCreateClick: () => void;
@@ -752,6 +803,12 @@ declare function WorkspaceTab({ workspaces, loading, onCreateClick: _onCreateCli
     onSwitchClick: (ws: WorkspaceInfo) => void;
     onLeaveClick: (ws: WorkspaceInfo) => void;
 }): react.JSX.Element;
+/**
+ * @deprecated Renamed to `WorkspaceListTab` in 0.4.0 — the tab is a workspace
+ * picker, not the settings of a workspace. Kept as an alias so consumers on
+ * the old name keep compiling.
+ */
+declare const WorkspaceTab: typeof WorkspaceListTab;
 declare function ReferralTab(): react.JSX.Element;
 interface SettingsContentProps {
     adapters: SettingsAdapters;
@@ -770,6 +827,44 @@ interface SettingsContentProps {
 }
 declare function SettingsContent({ adapters, activeTab, onClose, }: SettingsContentProps): react.JSX.Element;
 
+interface WorkspaceData {
+    id: string;
+    name: string;
+    initials: string;
+    role: string;
+    plan: string;
+    ownerEmail: string;
+    isCurrent: boolean;
+    imageUrl?: string;
+    imageName?: string;
+}
+interface WorkspaceModalProps {
+    open: boolean;
+    mode: "create" | "update";
+    workspace?: WorkspaceData | null;
+    onClose: () => void;
+    onCreate?: (name: string, imageFile: File | null) => void | boolean | Promise<void | boolean>;
+    onUpdate?: (name: string, imageFile: File | null, imageRemoved: boolean) => void | boolean | Promise<void | boolean>;
+    onLeave?: () => void | boolean | Promise<void | boolean>;
+    onDelete?: () => void | boolean | Promise<void | boolean>;
+}
+declare function WorkspaceModal({ open, mode, workspace, onClose, onCreate, onUpdate, onLeave, onDelete, }: WorkspaceModalProps): react.JSX.Element | null;
+
+interface WorkspaceGeneralTabProps {
+    /** The workspace being edited — always the currently active one. */
+    workspace: WorkspaceData | null;
+    loading: boolean;
+    /** Members in this workspace, when the host has counted them. */
+    memberCount?: number | null;
+    /** Name of the parent organization, when the workspace has joined one. */
+    organizationName?: string | null;
+    saving: boolean;
+    onSave: (name: string, imageFile: File | null, imageRemoved: boolean) => Promise<boolean>;
+    onLeave: () => void;
+    onDelete: () => void;
+}
+declare function WorkspaceGeneralTab({ workspace, loading, memberCount, organizationName, saving, onSave, onLeave, onDelete, }: WorkspaceGeneralTabProps): react.JSX.Element;
+
 type IconProps = Omit<SVGProps<SVGSVGElement>, 'color' | 'strokeWidth' | 'width' | 'height'> & {
     color?: string;
     strokeWidth?: number | string;
@@ -785,14 +880,36 @@ declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlan
     onShowPlansChange?: (open: boolean) => void;
 }): react__default.JSX.Element;
 
-declare function TeamsContent({ embedded, onInviteOpen, onInviteOpenChange, }?: {
+declare function TeamsContent({ embedded, onInviteOpen, onInviteOpenChange, workspaceName, workspaceImageUrl, organizationName, }?: {
     embedded?: boolean;
     onInviteOpen?: boolean;
     onInviteOpenChange?: (open: boolean) => void;
+    /**
+     * The workspace these members belong to. Supplied by the settings shell so
+     * the page can name its own subject — without it this screen was a list of
+     * people with no indication of which workspace they were in, and switching
+     * workspaces silently changed the contents.
+     */
+    workspaceName?: string | null;
+    workspaceImageUrl?: string;
+    /** Parent organization, when the workspace has joined one. */
+    organizationName?: string | null;
 }): react.JSX.Element;
 
-declare function OrganizationContent({ embedded, onInviteOpen, onInviteOpenChange, }?: {
+/**
+ * Which slice of the organization to show. The tab used to stack all three on
+ * one scrolling page, so the members table, the workspace list and the join
+ * requests competed for the same screen and the sections below the table were
+ * easy to miss entirely.
+ *
+ * `people` and `domains` split invites by kind on purpose: an email invite is
+ * a person you are expecting, a domain invite is a standing rule. They were
+ * interleaved in one "Pending" list, where a row could be either.
+ */
+type OrganizationView = "people" | "workspaces" | "domains";
+declare function OrganizationContent({ embedded, view, onInviteOpen, onInviteOpenChange, }?: {
     embedded?: boolean;
+    view?: OrganizationView;
     onInviteOpen?: boolean;
     onInviteOpenChange?: (open: boolean) => void;
 }): react.JSX.Element;
@@ -818,6 +935,84 @@ interface ProfileAvatarProps {
  */
 declare function ProfileAvatar({ name, profileImage, size, initialsClassName, borderRadius, }: ProfileAvatarProps): react.JSX.Element;
 
+interface ScopeHeaderProps {
+    /** Which level of the hierarchy this page acts on. */
+    kind: "workspace" | "organization";
+    /** The entity's own name. Falls back to the kind when still loading. */
+    name?: string | null;
+    imageUrl?: string;
+    /** The viewer's role in this entity. */
+    role?: "admin" | "member" | string | null;
+    /**
+     * Short factual phrases about the entity — member counts, parent org,
+     * workspace counts. Rendered as a single "·"-separated line; empty and
+     * nullish entries are dropped so callers can pass conditionals inline.
+     */
+    facts?: Array<string | null | undefined | false>;
+    /** Optional trailing control (e.g. a "Manage" button). */
+    action?: ReactNode;
+}
+declare function ScopeHeader({ kind, name, imageUrl, role, facts, action, }: ScopeHeaderProps): react.JSX.Element;
+/** `"1 member"` / `"12 members"` — keeps the plural out of every call site. */
+declare function countLabel(n: number, singular: string, plural?: string): string;
+
+type MemberListTab = "active" | "pending";
+interface MemberListToolbarProps {
+    activeTab: MemberListTab;
+    onTabChange: (tab: MemberListTab) => void;
+    /** Label for the left tab — "Active" for a workspace, "Members" for an org. */
+    activeLabel: string;
+    /** Row counts, appended to each tab label. Pass `null` while still loading. */
+    activeCount: number | null;
+    pendingCount: number | null;
+    searchQuery: string;
+    onSearchChange: (value: string) => void;
+    /** Optional trailing control, e.g. an Invite button on the page itself. */
+    action?: ReactNode;
+}
+declare function MemberListToolbar({ activeTab, onTabChange, activeLabel, activeCount, pendingCount, searchQuery, onSearchChange, action, }: MemberListToolbarProps): react.JSX.Element;
+interface MemberListFrameProps {
+    /** Column labels, pinned while the rows scroll under them. */
+    header?: ReactNode;
+    /** Shown in place of the rows when `isEmpty`. */
+    emptyText: string;
+    isEmpty: boolean;
+    /**
+     * `"fill"` claims the remaining height and scrolls internally — right for a
+     * page whose only content is the list. `"cap"` stops at `maxHeight` so
+     * sections below it stay reachable.
+     */
+    grow?: "fill" | "cap";
+    maxHeight?: number;
+    /**
+     * Minimum width of the rows. Member rows are a flexible identity column plus
+     * several fixed ones, so on a narrow screen the identity column is what
+     * collapses — leaving an avatar and a role chip with no name or email beside
+     * them. Holding the content to a minimum makes the frame scroll sideways
+     * instead, which keeps every column readable.
+     */
+    contentMinWidth?: number;
+    children?: ReactNode;
+}
+declare function MemberListFrame({ header, emptyText, isEmpty, grow, maxHeight, contentMinWidth, children, }: MemberListFrameProps): react.JSX.Element;
+/**
+ * A small pill marking a workspace member who is *also* a member of the
+ * organization above this workspace.
+ *
+ * It answers a question neither list used to acknowledge: removing someone
+ * here may not remove all their access. Per the org contract, admins of the
+ * parent organization keep implicit access to its workspaces, and a workspace
+ * set to organization-wide visibility is readable by every org member.
+ *
+ * Derived by intersecting this workspace's members with the organization's, so
+ * it states a fact both APIs already report — it is not a guess at an
+ * "inherited permission" flag, which no endpoint exposes.
+ */
+declare function OrgMembershipTag({ organizationName, isOrgAdmin, }: {
+    organizationName?: string | null;
+    isOrgAdmin?: boolean;
+}): react.JSX.Element;
+
 type SettingsTooltipPlacement = "right" | "top" | "bottom";
 interface SettingsTooltipProps {
     /** Explanation shown on hover / keyboard focus. Falsy renders the child bare. */
@@ -836,29 +1031,6 @@ interface SettingsTooltipProps {
 }
 declare function SettingsTooltip({ content, placement, delay, children, className, inline, }: SettingsTooltipProps): react.JSX.Element;
 
-interface WorkspaceData {
-    id: string;
-    name: string;
-    initials: string;
-    role: string;
-    plan: string;
-    ownerEmail: string;
-    isCurrent: boolean;
-    imageUrl?: string;
-    imageName?: string;
-}
-interface WorkspaceModalProps {
-    open: boolean;
-    mode: "create" | "update";
-    workspace?: WorkspaceData | null;
-    onClose: () => void;
-    onCreate?: (name: string, imageFile: File | null) => void | boolean | Promise<void | boolean>;
-    onUpdate?: (name: string, imageFile: File | null, imageRemoved: boolean) => void | boolean | Promise<void | boolean>;
-    onLeave?: () => void | boolean | Promise<void | boolean>;
-    onDelete?: () => void | boolean | Promise<void | boolean>;
-}
-declare function WorkspaceModal({ open, mode, workspace, onClose, onCreate, onUpdate, onLeave, onDelete, }: WorkspaceModalProps): react.JSX.Element | null;
-
 interface OrganizationData {
     id: string;
     name: string;
@@ -1002,4 +1174,4 @@ declare function SettingsAdaptersProvider({ adapters, children, }: {
  */
 declare function useSettingsAdapters(): SettingsAdapters;
 
-export { type ApiToken, type AvailableCreditsResponse, BillingContent, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, ConfirmDeleteModal, ConfirmLeaveModal, type CreatedToken, type CustomCreditInfo, type CustomCreditResponse, DEFAULT_PERMISSIONS, ExportDateModal, InviteUpdateModal, type InvoicePdfResponse, type MemberPermissionsPayload, OrganizationContent, type OrganizationData, type OrganizationInvite, OrganizationInviteModal, type OrganizationInviteModalProps, type OrganizationJoinRequest, type OrganizationMember, OrganizationModal, type OrganizationWorkspaceItem, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, ReferralTab, type ServiceItem, type SettingsAdapters, SettingsAdaptersProvider, type SettingsApiAdapter, type SettingsAuthAdapter, type SettingsAuthUser, SettingsContent, type SettingsContentProps, type SettingsImageUploadAdapter, type SettingsNavigationAdapter, type SettingsOrganizationAdapter, type SettingsOrganizationCurrent, type SettingsOrganizationListItem, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, SiconKey, type StoreItem, type SubscriptionPlan, type SubscriptionResponse, TAB_DESCRIPTIONS, TAB_LABELS, TAB_TO_URL, type TeamMember, TeamsContent, type TokenExpiry, TokensContent, URL_TO_TAB, type UpdateSubscriptionPayload, type UpdateSubscriptionResponse, type UsageHistoryItem, type UsageHistoryResponse, type UserPermissions, type WorkspaceData, type WorkspaceInvite, type WorkspaceMember, WorkspaceModal, WorkspaceTab, resolveSettingsTabFromPath, useSettingsAdapters };
+export { type ApiToken, type AvailableCreditsResponse, BillingContent, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, ConfirmDeleteModal, ConfirmLeaveModal, type CreatedToken, type CustomCreditInfo, type CustomCreditResponse, DEFAULT_PERMISSIONS, ExportDateModal, InviteUpdateModal, type InvoicePdfResponse, MemberListFrame, type MemberListFrameProps, type MemberListTab, MemberListToolbar, type MemberListToolbarProps, type MemberPermissionsPayload, OrgMembershipTag, OrganizationContent, type OrganizationData, type OrganizationInvite, OrganizationInviteModal, type OrganizationInviteModalProps, type OrganizationJoinRequest, type OrganizationMember, OrganizationModal, type OrganizationView, type OrganizationWorkspaceItem, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, ReferralTab, SCOPE_LABELS, ScopeHeader, type ScopeHeaderProps, type ServiceItem, type SettingsAdapters, SettingsAdaptersProvider, type SettingsApiAdapter, type SettingsAuthAdapter, type SettingsAuthUser, SettingsContent, type SettingsContentProps, type SettingsImageUploadAdapter, type SettingsNavigationAdapter, type SettingsOrganizationAdapter, type SettingsOrganizationCurrent, type SettingsOrganizationListItem, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, SiconKey, type StoreItem, type SubscriptionPlan, type SubscriptionResponse, TAB_DESCRIPTIONS, TAB_LABELS, TAB_SCOPE, TAB_TO_URL, type TeamMember, TeamsContent, type TokenExpiry, TokensContent, URL_TO_TAB, type UpdateSubscriptionPayload, type UpdateSubscriptionResponse, type UsageHistoryItem, type UsageHistoryResponse, type UserPermissions, type WorkspaceData, WorkspaceGeneralTab, type WorkspaceGeneralTabProps, type WorkspaceInvite, WorkspaceListTab, type WorkspaceMember, WorkspaceModal, WorkspaceTab, countLabel, resolveSettingsTabFromPath, useSettingsAdapters };