@basictech/react 0.12.0-beta.1 → 0.12.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @basictech/react
 
+## 0.12.0-beta.2
+
+### Minor Changes
+
+- 85388da: Add Base UI-backed account, auth, sync-status, avatar, and sharing components with optional scoped
+  styles and an appearance provider. Include a React DOM peer dependency for the portaled UI.
+  Add app-token project-profile read/update/reset APIs, React hook and settings editor, per-account
+  menu badges, and an optional avatar sync indicator.
+  Expose the components and project-profile hook through the Next.js client entry.
+  Share the saved-account registry between REST and sync modes, support add-account sign-in,
+  and keep cached display identity up to date after profile saves. Include read-only account
+  diagnostics with clipboard export and suppress sync badges in REST mode.
+
+### Patch Changes
+
+- Updated dependencies [85388da]
+  - @basictech/core@0.12.0-beta.2
+
 ## 0.12.0-beta.1
 
 ### Minor Changes

package/README.md

@@ -328,6 +328,93 @@ With the default `renderWhileLoading={false}`, hooks under the Provider first re
 client is ready. Setting it to `true` is useful for an application shell that reads `isReady` and
 owns its loading UI.
 
+## Prebuilt components
+
+Drop-in account and sharing UI uses Base UI's accessible menu, avatar, and dialog primitives.
+Components use the nearest `BasicProvider` (including `basic.Provider`); they do not create a
+second auth client. Import the optional stylesheet once. Omit it to supply your own styles.
+
+```tsx
+import {
+  BasicUIProvider, SignInButton, UserButton, AuthStatus, SyncStatus, SharesModal,
+} from '@basictech/react'
+import '@basictech/react/styles.css'
+import { basic } from './basic'
+
+export function AccountTools() {
+  return (
+    <basic.Provider>
+      <BasicUIProvider appearance={{ theme: 'light', accent: '#354f45', radius: '8px' }}>
+        <SignInButton />
+        <UserButton allowAddAccount />
+        <AuthStatus />
+        <SyncStatus />
+        <SharesModal scope={[{ table: 'todos', recordIds: ['todo-1'] }]} />
+      </BasicUIProvider>
+    </basic.Provider>
+  )
+}
+```
+
+| Component | Options and behavior |
+| --- | --- |
+| `BasicButton` | Native button props/ref; `variant="solid\|outline\|ghost"`. Defaults to `type="button"`. |
+| `SignInButton`, `SignOutButton` | Native button props and variant, pending/error feedback. Sign-in accepts `input` (handle/DID); `onClick.preventDefault()` cancels the action. Expired sessions can reauthorize or sign out. |
+| `UserAvatar` | Borderless avatar trigger for the shared user menu. Current account or explicit `profile` (`null` means guest); `size`, `className`, `style`; image failure falls back to initials. Sync badge defaults on in sync mode; `showSyncBadge={false}` hides it. REST mode never shows a sync badge. |
+| `UserButton` | Avatar, name, handle, and dropdown icon with a bordered hoverable trigger. `shape="rounded\|square"` defaults to rounded. Opens the shared user menu. Local accounts never show a handle. |
+| `UserMenu` | Shared menu used by both triggers; `trigger="avatar\|button"` defaults to avatar. Current account at top, Manage account, other saved accounts, and auth actions. The switch section appears only when other accounts exist. Only expired auth gets an `Expired` warning; no signed-in badge. `showSyncStatus={false}` hides the header's sync label; REST mode always hides sync badges. `allowAddAccount` defaults to true, starting sign-in in a new profile in REST or sync mode. Local accounts offer Clear account with a destructive-action confirmation. Optional `accountSettingsUrl`. |
+| `AuthStatus` | Loading, signed-in, guest, signed-out, recovering, and expired session labels. UI visibility is not authorization. |
+| `SyncStatus` | Connectivity, pending counts, and conflict/rejection count; optional `source` for a repo or mount. An online queue is not labelled synced. |
+| `AccountSettingsModal` | Profile tab edits the project display name with Cancel/Save changes; drafts survive tab switches. Advanced shows read-only DID, PDS URL, local account/storage identifiers, auth/write state, and sync counts. No tokens or credentials are rendered. Local accounts show explicit DID/PDS fallbacks. `projectProfile` supplies a complete preview hook result. Optional `accountSettingsUrl` links to universal identity settings; `children` adds host-owned Profile content. |
+| `SharesModal` | Same identity-header layout with Outgoing/Incoming tabs. Required explicit `scope`, optional `repo` (default: `'default'`). Viewer/editor invitations by handle/DID, outgoing list, refresh, confirmed cancellation/revocation. Incoming acceptance and mount management remain in Basic ID. |
+
+Both modals accept `open`/`onOpenChange`, an optional button element or label as `trigger`, and
+`finalFocus` for externally controlled use. `trigger={null}` omits the trigger. Custom trigger
+components must forward their ref and DOM props. Dialogs trap focus and close with Escape.
+
+`BasicUIProvider` accepts `appearance: { theme, accent, radius, density }`; density is
+`'comfortable'` or `'compact'`. Nested providers inherit appearance; portaled menus/dialogs retain
+it. Choose an accent with sufficient contrast against white for solid buttons. Fonts inherit from
+the host. Override the prefixed `basic-*` classes and `--basic-*` CSS tokens for finer styling.
+
+For controlled previews, components accept complete hook results via `auth`, `accounts`, `sync`,
+or `shares` as appropriate. These replace rendered state **and action callbacks**; a BasicProvider
+is still required and hooks still subscribe/read. Do not use these props as an authorization
+boundary. Real mutations remain subject to SDK and server permissions.
+
+Share creation requires an explicit nonempty table/record scope and defaults to viewer access.
+The list is labelled **all permissions**, not filtered to the new-invitation scope. Revocation cannot
+retract downloaded data. Signing out removes the account's local cache and pending edits.
+The incoming-invitations section links to Basic ID: inbox/accept/decline APIs require owner
+credentials, not app tokens. Server project-profile GET/PATCH/DELETE APIs exist at
+`/account/:project_id/profile` with `app:profile:read/update/delete` grants respectively.
+Configure those requested OAuth scopes and reauthorize existing sessions when needed.
+The shared menu shows sync status and any expiry warning with the current account in its header.
+Inactive accounts show saved expiry state, not the active account's sync status.
+Both `UserButton` and `UserAvatar` accept `showSyncBadge` (default follows SDK sync mode); circles use
+green for synced, blue for connecting/pending, orange for errors, gray for offline/local/idle.
+The demo's `?page=components` gallery offers live behavior, isolated simulated actions, design
+controls, and a copyable usage recipe. Live OAuth/shares require a configured signed-in account.
+
+### Project profile API
+
+`basic.useProjectProfile()` (also exported as `useProjectProfile`) returns `data`, `isLoading`,
+`error`, `refresh()`, `update(patch)`, and `reset()`. Pass `false` to disable automatic reads.
+`data` is `{ profile: { name?, avatar_url?, status? }, meta? }` or null before loading/sign-in.
+The core client exposes the same operations directly:
+
+```ts
+await basic.client.getProjectProfile()
+await basic.client.updateProjectProfile({ name: 'Name in this app', status: null })
+await basic.client.resetProjectProfile()
+```
+
+Requests always target the configured client ID using the active app token. Omitted fields stay
+unchanged; null removes an override. Metadata objects merge on the server; `meta: null` clears
+metadata. Reset removes all project overrides and metadata. Universal profile data is untouched.
+Permission failures propagate as SDK errors. Profile responses are not written into the local
+account registry; consumers needing the updated project identity should use this hook's data.
+
 ## Hook reference
 
 The schema-bound factory returns every hook below. Bound hooks are preferred because they reject
@@ -412,14 +499,16 @@ replicas and returns to another local profile or a fresh anonymous one when enab
 - `accounts: BasicAccount[]` lists local profiles with per-account auth summaries.
 - `activeAccount: BasicAccount | null` is this tab's selected profile and auth summary.
 - `switchAccount(id): Promise<void>` changes the active profile in this tab.
-- `addAccount(): Promise<BasicProfile>` creates and activates a new anonymous profile from which to
-  start another sign-in.
+- `addAccount({ signIn?: boolean }): Promise<BasicProfile>` creates and activates a new profile.
+  Omit options to stay local; pass `{ signIn: true }` to validate redirect configuration first and
+  start sign-in in the new profile. The prebuilt menu uses this sign-in option.
 - `removeAccount(id): Promise<void>` removes that profile and its local credentials/replicas. If it
   is active, this follows the sign-out path. It does not delete the server account.
 
 `BasicProfile` contains `id`, `kind: 'anon' | 'account'`, `storagePrefix`, `createdAt`,
-`lastActiveAt`, and optional/null `did`, `handle`, `email`, `name`, and `picture`. Multi-account and
-`addAccount()` require sync mode with anonymous profiles enabled.
+`lastActiveAt`, and optional/null `did`, `handle`, `email`, `name`, and `picture`. Saved accounts and
+switching work in REST and sync modes. `addAccount({ signIn: true })` works in either mode;
+`addAccount()` without sign-in still requires sync mode with anonymous profiles enabled.
 
 ```tsx
 // file: AccountSwitcher.tsx

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode, ReactElement } from 'react';
-import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
+import { ReactNode, ReactElement, RefObject, ButtonHTMLAttributes, HTMLAttributes } from 'react';
+import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus as AuthStatus$1, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, ProjectProfile, ProjectProfilePatch, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
 
 type BrowserBasicConfig<S extends BasicSchema = BasicSchema> = BasicConfig<S>;
 /** Create a core client with the complete browser adapter set installed. */
@@ -10,7 +10,9 @@ interface UseAccountsResult {
     accounts: BasicAccount[];
     activeAccount: BasicAccount | null;
     switchAccount(id: string): Promise<void>;
-    addAccount(): Promise<BasicProfile>;
+    addAccount(options?: {
+        signIn?: boolean;
+    }): Promise<BasicProfile>;
     removeAccount(id: string): Promise<void>;
 }
 declare function useAccounts(): UseAccountsResult;
@@ -21,7 +23,7 @@ interface UseAuthResult {
     isAnonymous: boolean;
     canWrite: boolean;
     readOnlyReason: ReadOnlyReason | null;
-    status: AuthStatus;
+    status: AuthStatus$1;
     /** Raw auth diagnostic; stable identity while its code and expired state are unchanged. */
     error: BasicError | null;
     user: AuthUser | null;
@@ -118,6 +120,19 @@ interface UseReposResult {
 }
 declare function useRepos(): UseReposResult;
 
+interface AsyncResult<T> {
+    data: T;
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+}
+
+interface UseProjectProfileResult extends AsyncResult<ProjectProfile | null> {
+    update(patch: ProjectProfilePatch): Promise<ProjectProfile>;
+    reset(): Promise<ProjectProfile>;
+}
+declare function useProjectProfile(enabled?: boolean): UseProjectProfileResult;
+
 type CreateBasicConfig<S extends BasicSchema> = BrowserBasicConfig<S> & {
     schema: S;
 };
@@ -147,6 +162,7 @@ interface CreatedBasic<S extends BasicSchema> {
     useSyncStatus(source?: SourceRef): UseSyncStatusResult;
     useSchemaStatus(source?: SourceRef): SchemaStatus;
     useRepos(): UseReposResult;
+    useProjectProfile(enabled?: boolean): UseProjectProfileResult;
     useFiles(query?: FileListQuery, options?: {
         source?: SourceRef;
     }): UseFilesResult;
@@ -180,6 +196,93 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
     source?: SourceRef;
 }): Collection<V>;
 
+interface BasicAppearance {
+    theme?: 'light' | 'dark';
+    accent?: string;
+    radius?: string;
+    density?: 'compact' | 'comfortable';
+}
+/** Optional styling provider. CSS is opt-in via @basictech/react/styles.css. */
+declare function BasicUIProvider({ appearance, children, }: {
+    appearance?: BasicAppearance;
+    children: ReactNode;
+}): react.JSX.Element;
+interface BasicButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: 'solid' | 'outline' | 'ghost';
+}
+declare const BasicButton: react.ForwardRefExoticComponent<BasicButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface AuthButtonProps extends BasicButtonProps {
+    auth?: UseAuthResult;
+    input?: string;
+}
+declare function SignInButton(props: AuthButtonProps): react.JSX.Element;
+declare function SignOutButton(props: AuthButtonProps): react.JSX.Element;
+interface UserAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    profile?: (Pick<BasicProfile, 'name' | 'handle' | 'email' | 'picture'> & Partial<Pick<BasicProfile, 'kind'>>) | null;
+    size?: number;
+    showSyncBadge?: boolean;
+    sync?: UseSyncStatusResult;
+    accounts?: UseAccountsResult;
+    auth?: UseAuthResult;
+    projectProfile?: UseProjectProfileResult;
+    allowAddAccount?: boolean;
+}
+declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+declare function AuthStatus({ auth: supplied, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
+    auth?: UseAuthResult;
+}): react.JSX.Element;
+declare function SyncStatus({ sync: supplied, source, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
+    sync?: UseSyncStatusResult;
+    source?: SourceRef;
+}): react.JSX.Element | null;
+interface UserButtonProps {
+    accounts?: UseAccountsResult;
+    auth?: UseAuthResult;
+    sync?: UseSyncStatusResult;
+    /** Show synchronization status in the account menu. Defaults to true. */
+    showSyncStatus?: boolean;
+    /** Defaults to enabled in sync mode. */
+    showSyncBadge?: boolean;
+    shape?: 'rounded' | 'square';
+    projectProfile?: UseProjectProfileResult;
+    /** Show the action to sign in to another account. Defaults to true. */
+    allowAddAccount?: boolean;
+    className?: string;
+    accountSettingsUrl?: string;
+}
+declare function UserButton(props: UserButtonProps): react.JSX.Element;
+interface UserMenuProps extends UserButtonProps {
+    trigger?: 'avatar' | 'button';
+    avatarProps?: UserAvatarProps;
+}
+declare function UserMenu({ accounts: supplied, auth: suppliedAuth, sync, showSyncStatus, showSyncBadge, shape, trigger, avatarProps, projectProfile, allowAddAccount, className, accountSettingsUrl, }: UserMenuProps): react.JSX.Element;
+interface BasicModalProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    finalFocus?: RefObject<HTMLElement>;
+    /** Supply a button element; null omits the trigger for controlled use. */
+    trigger?: ReactNode;
+}
+interface AccountSettingsModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    projectProfile?: UseProjectProfileResult;
+    sync?: UseSyncStatusResult;
+    accountSettingsUrl?: string;
+    children?: ReactNode;
+}
+declare function AccountSettingsModal({ auth: suppliedAuth, accounts: suppliedAccounts, accountSettingsUrl, projectProfile, sync, children, ...props }: AccountSettingsModalProps): react.JSX.Element;
+interface SharesModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    sync?: UseSyncStatusResult;
+    shares?: UseOutgoingSharesResult;
+    /** Explicit least-privilege scope; the component never infers all tables. */
+    scope: CreateOutgoingShareInput['scope'];
+    repo?: CreateOutgoingShareInput['repo'];
+}
+declare function SharesModal({ auth: supplied, accounts: suppliedAccounts, sync, shares, scope, repo, ...props }: SharesModalProps): react.JSX.Element;
+
 /** Synchronous browser Storage adapted to core's key-value contract. */
 declare class BrowserKeyValueStorage implements KeyValueStorage {
     private readonly storage;
@@ -275,4 +378,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-export { type AccessTokenAdopter, BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };
+export { type AccessTokenAdopter, AccountSettingsModal, type AccountSettingsModalProps, type AuthButtonProps, AuthStatus, type BasicAppearance, BasicButton, type BasicButtonProps, type BasicModalProps, BasicProvider, type BasicProviderProps, BasicUIProvider, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, SharesModal, type SharesModalProps, SignInButton, SignOutButton, SyncStatus, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseProjectProfileResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, UserAvatar, type UserAvatarProps, UserButton, type UserButtonProps, UserMenu, type UserMenuProps, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useProjectProfile, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode, ReactElement } from 'react';
-import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
+import { ReactNode, ReactElement, RefObject, ButtonHTMLAttributes, HTMLAttributes } from 'react';
+import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus as AuthStatus$1, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, ProjectProfile, ProjectProfilePatch, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
 
 type BrowserBasicConfig<S extends BasicSchema = BasicSchema> = BasicConfig<S>;
 /** Create a core client with the complete browser adapter set installed. */
@@ -10,7 +10,9 @@ interface UseAccountsResult {
     accounts: BasicAccount[];
     activeAccount: BasicAccount | null;
     switchAccount(id: string): Promise<void>;
-    addAccount(): Promise<BasicProfile>;
+    addAccount(options?: {
+        signIn?: boolean;
+    }): Promise<BasicProfile>;
     removeAccount(id: string): Promise<void>;
 }
 declare function useAccounts(): UseAccountsResult;
@@ -21,7 +23,7 @@ interface UseAuthResult {
     isAnonymous: boolean;
     canWrite: boolean;
     readOnlyReason: ReadOnlyReason | null;
-    status: AuthStatus;
+    status: AuthStatus$1;
     /** Raw auth diagnostic; stable identity while its code and expired state are unchanged. */
     error: BasicError | null;
     user: AuthUser | null;
@@ -118,6 +120,19 @@ interface UseReposResult {
 }
 declare function useRepos(): UseReposResult;
 
+interface AsyncResult<T> {
+    data: T;
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+}
+
+interface UseProjectProfileResult extends AsyncResult<ProjectProfile | null> {
+    update(patch: ProjectProfilePatch): Promise<ProjectProfile>;
+    reset(): Promise<ProjectProfile>;
+}
+declare function useProjectProfile(enabled?: boolean): UseProjectProfileResult;
+
 type CreateBasicConfig<S extends BasicSchema> = BrowserBasicConfig<S> & {
     schema: S;
 };
@@ -147,6 +162,7 @@ interface CreatedBasic<S extends BasicSchema> {
     useSyncStatus(source?: SourceRef): UseSyncStatusResult;
     useSchemaStatus(source?: SourceRef): SchemaStatus;
     useRepos(): UseReposResult;
+    useProjectProfile(enabled?: boolean): UseProjectProfileResult;
     useFiles(query?: FileListQuery, options?: {
         source?: SourceRef;
     }): UseFilesResult;
@@ -180,6 +196,93 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
     source?: SourceRef;
 }): Collection<V>;
 
+interface BasicAppearance {
+    theme?: 'light' | 'dark';
+    accent?: string;
+    radius?: string;
+    density?: 'compact' | 'comfortable';
+}
+/** Optional styling provider. CSS is opt-in via @basictech/react/styles.css. */
+declare function BasicUIProvider({ appearance, children, }: {
+    appearance?: BasicAppearance;
+    children: ReactNode;
+}): react.JSX.Element;
+interface BasicButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: 'solid' | 'outline' | 'ghost';
+}
+declare const BasicButton: react.ForwardRefExoticComponent<BasicButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface AuthButtonProps extends BasicButtonProps {
+    auth?: UseAuthResult;
+    input?: string;
+}
+declare function SignInButton(props: AuthButtonProps): react.JSX.Element;
+declare function SignOutButton(props: AuthButtonProps): react.JSX.Element;
+interface UserAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    profile?: (Pick<BasicProfile, 'name' | 'handle' | 'email' | 'picture'> & Partial<Pick<BasicProfile, 'kind'>>) | null;
+    size?: number;
+    showSyncBadge?: boolean;
+    sync?: UseSyncStatusResult;
+    accounts?: UseAccountsResult;
+    auth?: UseAuthResult;
+    projectProfile?: UseProjectProfileResult;
+    allowAddAccount?: boolean;
+}
+declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+declare function AuthStatus({ auth: supplied, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
+    auth?: UseAuthResult;
+}): react.JSX.Element;
+declare function SyncStatus({ sync: supplied, source, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
+    sync?: UseSyncStatusResult;
+    source?: SourceRef;
+}): react.JSX.Element | null;
+interface UserButtonProps {
+    accounts?: UseAccountsResult;
+    auth?: UseAuthResult;
+    sync?: UseSyncStatusResult;
+    /** Show synchronization status in the account menu. Defaults to true. */
+    showSyncStatus?: boolean;
+    /** Defaults to enabled in sync mode. */
+    showSyncBadge?: boolean;
+    shape?: 'rounded' | 'square';
+    projectProfile?: UseProjectProfileResult;
+    /** Show the action to sign in to another account. Defaults to true. */
+    allowAddAccount?: boolean;
+    className?: string;
+    accountSettingsUrl?: string;
+}
+declare function UserButton(props: UserButtonProps): react.JSX.Element;
+interface UserMenuProps extends UserButtonProps {
+    trigger?: 'avatar' | 'button';
+    avatarProps?: UserAvatarProps;
+}
+declare function UserMenu({ accounts: supplied, auth: suppliedAuth, sync, showSyncStatus, showSyncBadge, shape, trigger, avatarProps, projectProfile, allowAddAccount, className, accountSettingsUrl, }: UserMenuProps): react.JSX.Element;
+interface BasicModalProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    finalFocus?: RefObject<HTMLElement>;
+    /** Supply a button element; null omits the trigger for controlled use. */
+    trigger?: ReactNode;
+}
+interface AccountSettingsModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    projectProfile?: UseProjectProfileResult;
+    sync?: UseSyncStatusResult;
+    accountSettingsUrl?: string;
+    children?: ReactNode;
+}
+declare function AccountSettingsModal({ auth: suppliedAuth, accounts: suppliedAccounts, accountSettingsUrl, projectProfile, sync, children, ...props }: AccountSettingsModalProps): react.JSX.Element;
+interface SharesModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    sync?: UseSyncStatusResult;
+    shares?: UseOutgoingSharesResult;
+    /** Explicit least-privilege scope; the component never infers all tables. */
+    scope: CreateOutgoingShareInput['scope'];
+    repo?: CreateOutgoingShareInput['repo'];
+}
+declare function SharesModal({ auth: supplied, accounts: suppliedAccounts, sync, shares, scope, repo, ...props }: SharesModalProps): react.JSX.Element;
+
 /** Synchronous browser Storage adapted to core's key-value contract. */
 declare class BrowserKeyValueStorage implements KeyValueStorage {
     private readonly storage;
@@ -275,4 +378,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-export { type AccessTokenAdopter, BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };
+export { type AccessTokenAdopter, AccountSettingsModal, type AccountSettingsModalProps, type AuthButtonProps, AuthStatus, type BasicAppearance, BasicButton, type BasicButtonProps, type BasicModalProps, BasicProvider, type BasicProviderProps, BasicUIProvider, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, SharesModal, type SharesModalProps, SignInButton, SignOutButton, SyncStatus, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseProjectProfileResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, UserAvatar, type UserAvatarProps, UserButton, type UserButtonProps, UserMenu, type UserMenuProps, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useProjectProfile, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };