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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @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

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
@@ -334,6 +339,10 @@ Drop-in account and sharing UI uses Base UI's accessible menu, avatar, and dialo
 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,
@@ -372,10 +381,48 @@ Both modals accept `open`/`onOpenChange`, an optional button element or label as
 `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.
+### 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

package/dist/index.d.mts

@@ -198,6 +198,9 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
 
 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';
@@ -226,8 +229,9 @@ interface UserAvatarProps extends HTMLAttributes<HTMLSpanElement> {
     auth?: UseAuthResult;
     projectProfile?: UseProjectProfileResult;
     allowAddAccount?: boolean;
+    menuItems?: UserMenuItem[];
 }
-declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+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;
@@ -235,6 +239,19 @@ declare function SyncStatus({ sync: supplied, source, className, ...props }: HTM
     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;
@@ -249,13 +266,14 @@ interface UserButtonProps {
     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, }: UserMenuProps): react.JSX.Element;
+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;
@@ -378,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, 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 };
+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

@@ -198,6 +198,9 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
 
 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';
@@ -226,8 +229,9 @@ interface UserAvatarProps extends HTMLAttributes<HTMLSpanElement> {
     auth?: UseAuthResult;
     projectProfile?: UseProjectProfileResult;
     allowAddAccount?: boolean;
+    menuItems?: UserMenuItem[];
 }
-declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+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;
@@ -235,6 +239,19 @@ declare function SyncStatus({ sync: supplied, source, className, ...props }: HTM
     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;
@@ -249,13 +266,14 @@ interface UserButtonProps {
     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, }: UserMenuProps): react.JSX.Element;
+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;
@@ -378,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, 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 };
+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.js

@@ -1150,9 +1150,22 @@ var import_tabs = require("@base-ui/react/tabs");
 var import_core7 = require("@basictech/core");
 var import_jsx_runtime3 = require("react/jsx-runtime");
 var AppearanceContext = (0, import_react13.createContext)({});
+function accentText(accent) {
+  if (!/^#([\da-f]{3}|[\da-f]{6})$/i.test(accent)) return "#fff";
+  const hex = accent.length === 4 ? accent.slice(1).split("").map((digit) => digit + digit).join("") : accent.slice(1);
+  const [red, green, blue] = [0, 2, 4].map((offset) => {
+    const channel = parseInt(hex.slice(offset, offset + 2), 16) / 255;
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * red + 0.7152 * green + 0.0722 * blue > 0.179 ? "#000" : "#fff";
+}
 function appearanceStyle(appearance) {
   return {
-    ...appearance.accent ? { "--basic-accent": appearance.accent } : {},
+    ...appearance.base ? { "--basic-surface": appearance.base } : {},
+    ...appearance.accent ? {
+      "--basic-accent": appearance.accent,
+      "--basic-accent-text": accentText(appearance.accent)
+    } : {},
     ...appearance.radius ? { "--basic-radius": appearance.radius } : {}
   };
 }
@@ -1269,6 +1282,7 @@ function UserAvatar({
   auth,
   projectProfile,
   allowAddAccount,
+  menuItems,
   ...avatarProps
 }) {
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
@@ -1278,6 +1292,7 @@ function UserAvatar({
       auth,
       projectProfile,
       allowAddAccount,
+      menuItems,
       sync: avatarProps.sync,
       showSyncBadge: avatarProps.showSyncBadge,
       avatarProps
@@ -1406,7 +1421,8 @@ function UserMenu({
   projectProfile,
   allowAddAccount = true,
   className = "",
-  accountSettingsUrl
+  accountSettingsUrl,
+  menuItems = []
 }) {
   const liveAccounts = useAccounts();
   const liveAuth = useAuth();
@@ -1526,6 +1542,22 @@ function UserMenu({
             ]
           }
         ),
+        menuItems.map((item) => /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+          import_menu.Menu.Item,
+          {
+            className: "basic-menu-item",
+            render: item.href !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("a", { href: item.href }) : void 0,
+            disabled: item.disabled || action.pending,
+            onClick: () => {
+              if (item.onClick) void action.run(item.onClick);
+            },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { className: "basic-menu-icon", "aria-hidden": "true", children: item.icon }),
+              item.label
+            ]
+          },
+          item.id
+        )),
         (auth.isSignedIn || expired || active?.kind === "anon") && /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
           import_menu.Menu.Item,
           {
@@ -1582,7 +1614,7 @@ function UserMenu({
           },
           account.id
         )),
-        (allowAddAccount || !auth.isSignedIn && !expired) && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        (allowAddAccount || !auth.isSignedIn && !expired) && /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
           import_menu.Menu.Item,
           {
             className: "basic-menu-item",
@@ -1590,7 +1622,24 @@ function UserMenu({
             onClick: () => void action.run(
               () => allowAddAccount ? accounts.addAccount({ signIn: true }) : auth.signIn()
             ),
-            children: "\uFF0B Add account"
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+                "svg",
+                {
+                  className: "basic-menu-icon",
+                  width: "16",
+                  height: "16",
+                  viewBox: "0 0 24 24",
+                  fill: "none",
+                  stroke: "currentColor",
+                  strokeWidth: "1.75",
+                  strokeLinecap: "round",
+                  "aria-hidden": "true",
+                  children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("path", { d: "M12 5v14M5 12h14" })
+                }
+              ),
+              "Add account"
+            ]
           }
         )
       ] }) }) })