@buildbase/sdk 0.0.54 → 0.0.56

package/docs/THEMING.md

@@ -0,0 +1,67 @@
+# Theming the SDK UI
+
+All SDK components — settings screens, dialogs, banners, empty states, sidebar — are styled exclusively through CSS custom properties. To match your brand, override the variables; no component forks or `!important` hacks needed.
+
+## How it works
+
+The SDK stylesheet (`@buildbase/sdk/css/styles.css`) defines a default light theme on `:root` and a dark theme on `.dark`. Every color in the UI resolves from these variables, so overriding them re-skins everything at once.
+
+Values are **HSL triplets without the `hsl()` wrapper** (shadcn/ui convention), which lets the SDK derive tints — e.g. success banners use `hsl(var(--success) / 0.1)` for their background automatically.
+
+## Override example
+
+Load your overrides after the SDK stylesheet:
+
+```css
+:root {
+  /* Brand */
+  --primary: 262 83% 58%; /* your brand color — buttons, active nav, focus */
+  --primary-foreground: 0 0% 100%;
+  --radius: 0.75rem; /* corner rounding across all components */
+
+  /* Surfaces & text */
+  --background: 0 0% 100%;
+  --foreground: 240 10% 4%;
+  --muted: 240 5% 96%; /* subtle fills: loading bars, table headers */
+  --muted-foreground: 240 4% 46%; /* secondary text, hints, labels */
+  --border: 240 6% 90%;
+
+  /* Status colors — banners, badges, progress bars */
+  --destructive: 0 84% 60%; /* errors, danger zone, overage */
+  --success: 142 72% 29%; /* success banners, paid badges, checkmarks */
+  --warning: 26 90% 37%; /* warnings, expiring credits, near-limit */
+  --info: 224 76% 48%; /* info notices, selected plans, usage bars */
+}
+```
+
+## Full variable reference
+
+| Variable                                     | Used for                                        |
+| -------------------------------------------- | ----------------------------------------------- |
+| `--background` / `--foreground`              | Page surface and main text                      |
+| `--card` / `--card-foreground`               | Card surfaces                                   |
+| `--popover` / `--popover-foreground`         | Dropdowns, popovers                             |
+| `--primary` / `--primary-foreground`         | Buttons, active sidebar item, selected states   |
+| `--secondary` / `--secondary-foreground`     | Secondary buttons                               |
+| `--muted` / `--muted-foreground`             | Subtle fills, secondary text, disabled states   |
+| `--accent` / `--accent-foreground`           | Hover highlights                                |
+| `--destructive` / `--destructive-foreground` | Errors, delete actions, overage indicators      |
+| `--success` / `--success-foreground`         | Success banners, active/paid badges             |
+| `--warning` / `--warning-foreground`         | Warnings, permission notices, near-limit states |
+| `--info` / `--info-foreground`               | Info notices, plan highlights, usage bars       |
+| `--border` / `--input` / `--ring`            | Borders, input outlines, focus rings            |
+| `--radius`                                   | Border radius scale (lg/md/sm derive from it)   |
+
+## Dark mode
+
+Add the `.dark` class to a root element and override the same variables under `.dark { … }`. The SDK ships dark defaults for every variable.
+
+## Components that work without the stylesheet
+
+`FullScreenLoader` and the `ErrorBoundary` fallback use inline styles so they render correctly before/without CSS loading. They still read the variables (with hard-coded fallbacks), so brand overrides apply to them too once your CSS is present.
+
+## Rules for SDK contributors
+
+- Never use Tailwind palette classes (`gray-*`, `blue-*`, `red-*`, `green-*`, `amber-*`, `slate-*`, `bg-white`, `text-white`) in components — they bypass theming. Use the semantic tokens above.
+- Soft status fills are alpha tints of the token: `bg-success/10` (background), `border-success/20` (border), `text-success` (text).
+- CI-check locally: `grep -rE '(bg|text|border|divide)-[a-z]+-[0-9]{2,3}|bg-white|text-white|#[0-9a-fA-F]{3,6}' src/components src/providers --include='*.tsx'` should return nothing (the pattern catches every Tailwind palette shade and raw hex).

package/docs/UI-CONFIG.md

@@ -0,0 +1,207 @@
+# UI Configuration (`ui` prop)
+
+Control which parts of the SDK UI are shown and override individual UI strings — without forking components or abusing the permission system.
+
+Everything is driven by a single optional `ui` prop on `SaaSOSProvider`:
+
+```tsx
+<SaaSOSProvider serverUrl="..." version="v1" orgId="..." ui={{ ... }}>
+```
+
+## Principles
+
+1. **Everything defaults to visible.** The `ui` prop is never required; an empty or missing config means current behavior. Only an explicit `false` hides something.
+2. **Config can only hide, never force-show.** A visible flag never bypasses platform permissions — a user without `WORKSPACE_BILLING_VIEW` won't see the Subscription section no matter what the config says. Permissions remain the security floor.
+3. **One decision, one call.** Internally every gated surface resolves through `useUIVisibility()`, which combines the config flag and the permission check in a single call. Your own components can use the same hook.
+
+## How visibility is decided
+
+A piece of SDK UI is shown when **all** of these pass:
+
+| Layer               | Source                                | Example                                      |
+| ------------------- | ------------------------------------- | -------------------------------------------- |
+| Implementor config  | `ui` prop (this doc)                  | `settings.sections.credits !== false`        |
+| Platform permission | user's role, resolved per workspace   | `can(Permission.WORKSPACE_BILLING_VIEW)`     |
+| Workspace mode      | server settings (`personal/platform`) | personal mode hides Users/Permissions/Danger |
+| Server settings     | org settings from the backend         | `settings.workspace.showSwitcher`            |
+
+## Settings dialog sections
+
+`ui.settings.sections` hides whole sections of the workspace settings dialog. Keys match the `SettingsScreen` values:
+
+`profile` · `security` · `connected-agents` · `general` · `users` · `subscription` · `usage` · `credits` · `features` · `notifications` · `permissions` · `danger`
+
+```tsx
+ui={{
+  settings: {
+    sections: { credits: false, notifications: false, 'connected-agents': false },
+  },
+}}
+```
+
+Hiding a section removes it from the sidebar (a fully-empty group collapses, including its header), and makes the screen unreachable via deep links, `defaultSection`, or the settings-manager — the dialog falls back to the first enabled section. If every section is hidden, the dialog renders nothing.
+
+## Per-screen toggles
+
+Fine-grained switches inside each settings screen. All default to `true`.
+
+| Config key                            | Hides                                                                    |
+| ------------------------------------- | ------------------------------------------------------------------------ |
+| `settings.profile.language`           | Language dropdown                                                        |
+| `settings.profile.country`            | Country dropdown                                                         |
+| `settings.profile.currency`           | Currency dropdown                                                        |
+| `settings.profile.timezone`           | Timezone dropdown                                                        |
+| `settings.security.passkeyRename`     | Rename action on passkey rows                                            |
+| `settings.security.passkeyDelete`     | Delete action on passkey rows                                            |
+| `settings.general.nameEdit`           | Workspace name field                                                     |
+| `settings.general.iconEditor`         | Emoji/image icon editor                                                  |
+| `settings.users.invite`               | Invite-member form                                                       |
+| `settings.users.roleChange`           | Per-member role selector                                                 |
+| `settings.users.remove`               | Remove-member button                                                     |
+| `settings.users.seatPricing`          | Seat usage card + extra-seat cost warnings                               |
+| `settings.subscription.changePlan`    | Every plan-picker entry point (change plan, view plans, upgrade banners) |
+| `settings.subscription.cancel`        | Cancel-subscription button (Resume stays available)                      |
+| `settings.subscription.managePayment` | Stripe billing-portal button                                             |
+| `settings.subscription.invoicesTab`   | Invoices tab (tab bar collapses; past-due "view invoices" links too)     |
+| `settings.subscription.planDetails`   | Features/limits/quotas breakdown on the plan card                        |
+| `settings.credits.buyButton`          | Buy-credits button + packages dialog                                     |
+| `settings.credits.transactions`       | Recent-transactions list                                                 |
+| `settings.notifications.push`         | Browser push-notification block                                          |
+| `settings.notifications.emailToggles` | Per-event email preference column                                        |
+| `settings.notifications.pushToggles`  | Per-event push preference column                                         |
+
+```tsx
+ui={{
+  settings: {
+    subscription: { cancel: false, invoicesTab: false },
+    users: { invite: false, seatPricing: false },
+  },
+}}
+```
+
+## Workspace switcher
+
+Client-side switcher control, ANDed with the server settings (`showSwitcher`, `canCreateWorkspace`):
+
+| Config key                       | Hides                                        |
+| -------------------------------- | -------------------------------------------- |
+| `workspaceSwitcher.show`         | The switcher dialog (trigger opens settings) |
+| `workspaceSwitcher.createButton` | "Create workspace" button                    |
+| `workspaceSwitcher.planBadge`    | Subscription-plan badge on workspace rows    |
+| `workspaceSwitcher.memberCount`  | Member count on workspace rows               |
+
+## Behavior
+
+| Config key                    | Effect                                                                                                                                                           |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `behavior.autoOpenPlanDialog` | `false` disables the automatic plan-picker popup when a workspace has no subscription. Explicit `selectPlan` deep links (e.g. from `PricingPage`) still open it. |
+| `behavior.trialEndingDays`    | Global default threshold for `<WhenTrialEnding>` (default 3). A `daysThreshold` prop still wins per usage.                                                       |
+
+## String overrides (`messages`)
+
+Override any SDK UI string per key — deep-merged over the active locale bundle. Ideal for rebranding terms without forking the 8 locale files:
+
+```tsx
+ui={{
+  messages: {
+    settings: { sidebar: { credits: 'Tokens', subscription: 'Billing' } },
+    credits: { buyCredits: 'Buy Tokens' },
+  },
+}}
+```
+
+- Keys/shape mirror `SDKMessages` (see `src/i18n/types.ts`); the type is `PartialSDKMessages`.
+- Overrides apply on top of whichever locale is active.
+- Missing keys in a locale (or in your overrides) fall back to English before falling back to the raw key.
+
+## Error boundary
+
+The top-level error boundary renders even when the i18n layer has crashed, so its strings are plain values, not translation keys:
+
+```tsx
+ui={{ errorBoundary: { title: 'Oops, something broke', retryLabel: 'Retry' } }}
+```
+
+## Date formats
+
+`ui.formats.date` takes `Intl.DateTimeFormatOptions` and applies to dates the SDK renders (passkey activity, connected-agent grants). Default: `{ dateStyle: 'medium' }`.
+
+```tsx
+ui={{ formats: { date: { dateStyle: 'short' } } }}
+```
+
+## Per-dialog override
+
+`WorkspaceSettingsDialog` accepts its own `ui` prop, deep-merged over the provider-global config — so one app can render differently-configured dialogs:
+
+```tsx
+// Global config hides credits everywhere…
+<SaaSOSProvider ui={{ settings: { sections: { credits: false } } }}>
+
+// …but this admin-only dialog shows everything except Danger
+<WorkspaceSettingsDialog
+  workspace={ws}
+  ui={{ settings: { sections: { credits: true, danger: false } } }}
+/>
+```
+
+## Using the same gating in your own UI
+
+```tsx
+import { useUIVisibility, useUIConfig, Permission } from '@buildbase/sdk/react';
+
+function MembersPanel() {
+  const { visible } = useUIVisibility();
+
+  // Config flag AND permission — one line decides show/hide
+  if (!visible(ui => ui.settings?.users?.invite, Permission.WORKSPACE_MEMBERS_INVITE)) {
+    return null;
+  }
+  return <InviteForm />;
+}
+```
+
+- `visible(select, permission?)` — `true` unless the selected flag is explicitly `false`, and (when given) the permission check passes. Works with app permissions too: `visible(ui => ui.settings?.sections?.usage, 'reports:view')`.
+- `useUIConfig()` — the raw `ui` object when you only need config values (e.g. `formats`, `behavior`).
+- `mergeUIConfig(base, override)` — the deep-merge used for per-dialog overrides, exported for custom composition.
+
+## Recipes
+
+**Single-tenant app (no workspaces UX):**
+
+```tsx
+ui={{
+  workspaceSwitcher: { show: false, createButton: false },
+  settings: { sections: { users: false, permissions: false, danger: false } },
+}}
+```
+
+**Billing handled outside the SDK:**
+
+```tsx
+ui={{
+  settings: { sections: { subscription: false, credits: false, usage: false } },
+  behavior: { autoOpenPlanDialog: false },
+}}
+```
+
+**White-label rename:**
+
+```tsx
+ui={{
+  messages: { settings: { sidebar: { credits: 'Tokens' }, titles: { credits: 'Tokens' } } },
+  errorBoundary: { title: 'Something went wrong at Acme' },
+}}
+```
+
+**Read-only member view (UI-level; permissions still enforce server-side):**
+
+```tsx
+ui={{
+  settings: {
+    users: { invite: false, roleChange: false, remove: false },
+    general: { nameEdit: false, iconEditor: false },
+    security: { passkeyRename: false, passkeyDelete: false },
+  },
+}}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildbase/sdk",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "type": "module",
   "description": "A SDK for Buildbase",
   "main": "dist/index.cjs",
@@ -57,7 +57,12 @@
     "dist",
     "README.md",
     "AGENTS.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/ARCHITECTURE.md",
+    "docs/ERROR_CODES.md",
+    "docs/MCP-AND-AGENT-READINESS.md",
+    "docs/THEMING.md",
+    "docs/UI-CONFIG.md"
   ],
   "sideEffects": [
     "**/*.css"
@@ -78,8 +83,9 @@
     "yalc:remove": "yalc remove",
     "format": "prettier --write . --plugin=prettier-plugin-organize-imports",
     "format:check": "prettier --check . --plugin=prettier-plugin-organize-imports",
-    "lint": "npm run lint:types && npm run lint:tokens",
+    "lint": "npm run lint:types && npm run lint:tokens && npm run lint:i18n",
     "lint:types": "tsc --noEmit",
+    "lint:i18n": "node scripts/check-i18n.mjs",
     "lint:tokens": "grep -rEn '(bg|text|border|divide|ring|outline|from|via|to|fill|stroke|shadow|ring-offset)-(gray|slate|red|green|emerald|amber|yellow|blue|purple|pink|indigo|violet|orange|teal|cyan|lime|rose|fuchsia|sky|stone|zinc|neutral)-[0-9]+|bg-white|text-white|#[0-9a-fA-F]{6}' src/components src/providers --include='*.tsx' && echo 'Hard-coded colors found — use theme tokens (see docs/THEMING.md)' && exit 1 || exit 0",
     "push:sdk": "npm run build && yalc push",
     "watch:push": "nodemon",
@@ -91,6 +97,7 @@
   },
   "dependencies": {
     "@hookform/resolvers": "^5.0.1",
+    "@radix-ui/react-accordion": "^1.2.16",
     "@radix-ui/react-alert-dialog": "^1.1.13",
     "@radix-ui/react-avatar": "^1.1.9",
     "@radix-ui/react-dialog": "^1.1.13",
@@ -165,6 +172,10 @@
     "express"
   ],
   "author": "Buildbase",
+  "homepage": "https://buildbase.app",
+  "bugs": {
+    "email": "support@buildbase.app"
+  },
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"