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

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, 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, 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. */
@@ -8,9 +8,11 @@ declare function createBasicClient<S extends BasicSchema>(config: BrowserBasicCo
 
 interface UseAccountsResult {
     accounts: BasicAccount[];
-    active: BasicAccount | null;
+    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;
@@ -20,8 +22,9 @@ interface UseAuthResult {
     isSignedIn: boolean;
     isAnonymous: boolean;
     canWrite: boolean;
-    readOnlyReason: string | null;
-    status: AuthStatus;
+    readOnlyReason: ReadOnlyReason | null;
+    status: AuthStatus$1;
+    /** Raw auth diagnostic; stable identity while its code and expired state are unchanged. */
     error: BasicError | null;
     user: AuthUser | null;
     did: string | null;
@@ -64,6 +67,7 @@ declare function useFiles(query?: FileListQuery, options?: {
 interface UseStorageInfoResult {
     data: StorageInfo | null;
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
 }
@@ -71,8 +75,8 @@ declare function useStorageInfo(): UseStorageInfoResult;
 
 interface UseMountsResult<S extends BasicSchema = BasicSchema> {
     data: MountInfo[];
-    mounts: MountInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     open(mountId: string): Promise<MountHandle<S>>;
@@ -81,8 +85,8 @@ interface UseMountsResult<S extends BasicSchema = BasicSchema> {
 declare function useMounts(query?: MountsQuery): UseMountsResult;
 interface UseOutgoingSharesResult {
     data: OutgoingShareInfo[];
-    outgoingShares: OutgoingShareInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>;
@@ -116,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;
 };
@@ -145,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;
@@ -178,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;
@@ -211,6 +316,8 @@ declare class BrowserTokenStore implements TokenStore {
     private waitForAccessToken;
 }
 
+/** The subset of BrowserTokenStore the auth channel needs; any token store providing it works. */
+type AccessTokenAdopter = Pick<BrowserTokenStore, 'accessToken' | 'adoptAccessToken'>;
 interface BrowserMessageChannel {
     postMessage(message: unknown): void;
     close(): void;
@@ -223,9 +330,11 @@ declare function createBrowserMessageChannel(name: string): BrowserMessageChanne
 /**
  * Access tokens may cross tabs transiently but are never written to browser
  * storage. The receiving adapter adopts the token before core handles the
- * ordinary token-rotation notification.
+ * ordinary token-rotation notification. Core supplies the token key for the
+ * profile's auth channel; channels without a context (the accounts channel)
+ * are plain BroadcastChannels.
  */
-declare function createBrowserAuthChannelFactory(clientId: string, tokenStore: BrowserTokenStore): (name: string) => AuthMessageChannel;
+declare function createBrowserAuthChannelFactory(tokenStore: AccessTokenAdopter): (name: string, context?: AuthChannelContext) => AuthMessageChannel;
 
 declare function browserNavigate(url: string): void;
 declare function browserCurrentUrl(): string;
@@ -269,4 +378,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-export { 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 };