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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @basictech/react
 
+## 0.12.0-beta.3
+
+### Minor Changes
+
+- fc5772a: Add app-owned menu actions and links with optional icons to UserAvatar, UserButton, and UserMenu.
+  Add a base background color to BasicUIProvider, derive borders and hover backgrounds from it,
+  and choose black or white text for hex accent colors. Preserve appearance in menu and modal
+  portals. Document component selection, simple theming, menu extensions, and Base UI dependencies.
+
+### Patch Changes
+
+- @basictech/core@0.12.0-beta.3
+
+## 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

@@ -18,14 +18,19 @@ its package metadata.
 
 ## Install
 
-This README describes the `0.12.0-beta.1` release candidate. After publication, install
+This README describes `0.12.0-beta.3`. After publication, install
 matching versions of the React SDK and the schema package you import directly:
 
 ```bash
-npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
+npm install @basictech/react@0.12.0-beta.3 @basictech/schema@0.12.0-beta.3
 ```
 
-React is a peer dependency and must already be installed by your application.
+React and React DOM (18+) are peer dependencies and must already be installed by your application.
+Use Node.js 24+ for development, CI, and builds to match the supported engine range.
+`@base-ui/react` (`^1.8.0`) is installed automatically as a dependency, not a peer.
+We import its `avatar`, `dialog`, `menu`, and `tabs` subpaths and leave them external in the SDK
+build. Your app's bundler resolves those imports; we do not bundle the entire Base UI library
+inside the SDK. Installing the dependency does install the Base UI package on disk.
 
 ## Auth update guide
 
@@ -33,9 +38,9 @@ Upgrade the packages you use together. npm's `latest` channel remains on `0.11.0
 does not contain all of the API changes described here:
 
 ```bash
-npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
+npm install @basictech/react@0.12.0-beta.3 @basictech/schema@0.12.0-beta.3
 # If you import core directly, update that dependency too:
-npm install @basictech/core@0.12.0-beta.1
+npm install @basictech/core@0.12.0-beta.3
 ```
 
 Keep the public packages on matching versions. No browser storage reset or persisted-profile
@@ -328,6 +333,135 @@ 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.
+
+**Which one should I use?** `UserButton` gives you the avatar, name, handle, and menu.
+Choose `UserAvatar` for the same menu with an avatar-only trigger. `UserMenu` is the shared
+component underneath both; you normally do not need to render it separately.
+
+```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.
+
+### Simple colors and custom menu items
+
+`appearance.base`, automatic accent contrast, and `menuItems` require `0.12.0-beta.3` or newer;
+they are not available in beta.2.
+
+Start with `theme: 'light'` or `'dark'`. Optionally set a `base` background and an `accent`.
+Light mode uses black text; dark mode uses white text, with muted shades for secondary text.
+Borders and hover backgrounds follow the base color. Choose a light base for light mode and a
+dark base for dark mode. Omit the accent for neutral black/white buttons. For an accent, use
+`#RGB` or `#RRGGBB`: solid buttons automatically choose black or white text for contrast.
+Other CSS accent values retain white foreground text; check their contrast yourself.
+
+```tsx
+import { BasicUIProvider, UserButton } from '@basictech/react'
+import '@basictech/react/styles.css'
+
+// Inside your existing BasicProvider. openPreferences is your app's callback.
+<BasicUIProvider appearance={{ theme: 'dark', base: '#201d17', accent: '#d4af37' }}>
+  <UserButton menuItems={[
+    { id: 'preferences', label: 'Preferences', onClick: openPreferences },
+    { id: 'about', label: 'About', href: '/about' },
+  ]} />
+</BasicUIProvider>
+```
+
+`UserAvatar`, `UserButton`, and `UserMenu` all accept `menuItems`. Each item has a unique `id`,
+`label`, either `href` or `onClick`, and optional `icon` (a React node) and `disabled`.
+Icons are decorative, sized to 16px, and can come from your app's existing icon library:
+`{ id: 'preferences', label: 'Preferences', icon: <SettingsIcon />, onClick: openPreferences }`.
+Items appear after Manage account and before Sign out/Clear account. Selecting an item closes
+the menu; async action failures use the SDK's dismissible error dialog. Use `onClick` to call
+your router when you need client-side navigation rather than a normal link.
+
+Nested appearance providers inherit settings, including in portaled menus and modals.
+Pass your app's current light/dark mode to `theme`; there is no separate theme listener.
+Existing `radius` and `density: 'comfortable' | 'compact'` options remain available.
+Fonts inherit from the host. No icon pack or additional provider is needed.
+
+To replace custom auth UI, keep your existing BasicProvider, import the stylesheet once,
+and replace the old avatar/dropdown with `UserButton` or `UserAvatar`. Move app-owned actions
+into `menuItems`; account switching and sign-out remain SDK-managed. `accountSettingsUrl`
+only adds a link inside the built-in settings modal—it does not replace Manage account.
+
+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 +546,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,111 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
     source?: SourceRef;
 }): Collection<V>;
 
+interface BasicAppearance {
+    theme?: 'light' | 'dark';
+    /** Background color. Choose a light or dark base to match the theme. */
+    base?: string;
+    /** Hex colors get automatic black/white foreground contrast. */
+    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;
+    menuItems?: UserMenuItem[];
+}
+declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, menuItems, ...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;
+/** App-owned items appear after Manage account and before Sign out. */
+type UserMenuItem = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+} & ({
+    href: string;
+    onClick?: never;
+} | {
+    onClick: () => void | Promise<void>;
+    href?: never;
+});
+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;
+    menuItems?: UserMenuItem[];
+}
+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, menuItems, }: 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 +396,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 UserMenuItem, 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,111 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
     source?: SourceRef;
 }): Collection<V>;
 
+interface BasicAppearance {
+    theme?: 'light' | 'dark';
+    /** Background color. Choose a light or dark base to match the theme. */
+    base?: string;
+    /** Hex colors get automatic black/white foreground contrast. */
+    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;
+    menuItems?: UserMenuItem[];
+}
+declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, menuItems, ...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;
+/** App-owned items appear after Manage account and before Sign out. */
+type UserMenuItem = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+} & ({
+    href: string;
+    onClick?: never;
+} | {
+    onClick: () => void | Promise<void>;
+    href?: never;
+});
+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;
+    menuItems?: UserMenuItem[];
+}
+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, menuItems, }: 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 +396,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 UserMenuItem, 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 };