orbcafe-ui 2.0.0 → 2.0.1

package/BRAND_THEMING.md

@@ -0,0 +1,45 @@
+# Brand Theming
+
+ORBCAFE UI ships with the ORBIS theme as its default. Open Design is optional:
+it is only needed when a project wants to discover and apply brand presets stored
+on the developer's machine.
+
+## Built-in theme packs
+
+Projects without Open Design can import the packaged themes directly. Import the
+base styles first, then one theme override:
+
+```ts
+import 'orbcafe-ui/styles.css';
+import 'orbcafe-ui/themes/orbis.css';
+// or: import 'orbcafe-ui/themes/nvidia.css';
+```
+
+The ORBIS theme is already included by `orbcafe-ui/styles.css`; importing its
+theme pack is useful when an application wants the packaged Montserrat font files
+and explicit ORBIS overrides.
+
+## Open Design presets
+
+The optional CLI discovers local Open Design systems and generates a project-local
+theme pack containing CSS variables, fonts, and JavaScript tokens:
+
+```bash
+npx orbcafe-theme list --json
+npx orbcafe-theme apply <slug> --json
+```
+
+Import the generated CSS after the base styles:
+
+```ts
+import 'orbcafe-ui/styles.css';
+import './orbcafe-theme/<slug>.css';
+```
+
+Use the generated `.tokens.mjs` file for charts or canvas code that cannot read
+CSS custom properties. If Open Design is unavailable, the default ORBIS theme and
+the built-in theme packs remain available; no runtime connection to Open Design is
+required by ORBCAFE components.
+
+Only one brand override should be active at a time. Regenerate generated files
+with the CLI when the source design system changes instead of editing them by hand.

package/MIGRATION_V2.md

@@ -0,0 +1,161 @@
+# Migrating ORBCAFE UI from v1 to v2
+
+`orbcafe-ui@2` is a breaking major release. It replaces the MUI-based implementation with the ORBIS design system, changes the theme integration, and requires host-side Tailwind configuration. Upgrade in a branch and verify the application before releasing it.
+
+## Supported baseline
+
+- Next.js 13-16. The canonical setup is Next.js App Router.
+- React 18 or 19.
+- Tailwind CSS 4.
+- Import public APIs only from `orbcafe-ui`.
+
+## 1. Upgrade dependencies
+
+```bash
+npm install orbcafe-ui@^2
+npm install -D tailwindcss@^4 @tailwindcss/postcss@^4
+```
+
+ORBCAFE UI v2 does not require `@mui/*`, `@emotion/*`, `lucide-react`, or `next-themes`. Remove them only when the host application does not use them for anything else.
+
+## 2. Configure PostCSS and global CSS
+
+Use the Tailwind v4 PostCSS plugin:
+
+```js
+// postcss.config.mjs
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;
+```
+
+Import the ORBIS stylesheet once and scan the published library output. Adjust the relative `@source` path if the global CSS file is nested differently.
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "orbcafe-ui/styles.css";
+@source "../node_modules/orbcafe-ui/dist";
+```
+
+Without both the stylesheet import and source scan, components may render without their complete layout and interaction styles.
+
+## 3. Configure application providers
+
+Mount `GlobalMessage` once. Use `OrbisModeProvider` at the application layer when standalone ORBCAFE surfaces or the host design system need the same mode.
+
+```tsx
+'use client';
+
+import { GlobalMessage, OrbisModeProvider } from 'orbcafe-ui';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <OrbisModeProvider mode="system">
+      {children}
+      <GlobalMessage />
+    </OrbisModeProvider>
+  );
+}
+```
+
+`CAppPageLayout` renders its own ORBIS mode provider. In the next v2 patch it also accepts controlled `mode`, `defaultMode`, and `onModeChange` props, allowing a host theme store to synchronize it directly.
+
+## 4. Use the standard application shell
+
+Prefer `CAppPageLayout` over manually combining `CAppHeader`, `NavigationIsland`, and `usePageLayout`.
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import {
+  CAppPageLayout,
+  type OrbModeSetting,
+  type TreeMenuItem,
+} from 'orbcafe-ui';
+
+const menuData: TreeMenuItem[] = [
+  {
+    id: 'reports',
+    title: 'Reports',
+    pinnable: false,
+    children: [
+      { id: 'sales-report', title: 'Sales Report', href: '/reports/sales' },
+    ],
+  },
+];
+
+export function AppShell({ children }: { children: React.ReactNode }) {
+  const [mode, setMode] = useState<OrbModeSetting>('system');
+
+  return (
+    <CAppPageLayout
+      appId="customer-portal"
+      appTitle="Customer Portal"
+      menuData={menuData}
+      mode={mode}
+      onModeChange={setMode}
+      logo={<img src="/brand/logo.svg" alt="Customer Portal" width={36} height={36} />}
+    >
+      {children}
+    </CAppPageLayout>
+  );
+}
+```
+
+The `appId` prop is available in the next v2 patch. It creates stable application-wide storage keys without depending on a localized or page-specific `appTitle`. On v2.0.0, pass one explicit `navigationPinStorageKey` everywhere instead.
+
+## 5. Stabilize navigation persistence
+
+- Treat every `TreeMenuItem.id` as a durable identifier. Do not translate or regenerate it.
+- Give navigable leaves a stable `href` or `appurl`.
+- Set `pinnable: false` on group and synthetic nodes.
+- Use one `appId` or one `navigationPinStorageKey` for the entire application.
+- For zero first-paint movement, load pin preferences from a server profile or cookie and pass controlled `pinnedNavigationItemIds` with `onPinnedNavigationItemIdsChange`.
+- LocalStorage-only persistence is hydration-safe but is restored after mount, so a short pinned-section appearance is possible.
+
+## 6. Replace MUI-specific integration
+
+- Import icons from `orbcafe-ui` instead of MUI or Lucide packages.
+- Replace MUI `ThemeProvider`, `CssBaseline`, and date-picker providers when they existed only for ORBCAFE UI.
+- Review every public `sx` value. ORBCAFE v2 `sx` uses the ORBIS compatibility contract and does not execute MUI theme callbacks.
+- Replace responsive MUI `sx` objects with host CSS/media queries where needed.
+- Import only from the package root. The v2 `exports` map intentionally blocks unsupported internal paths such as `orbcafe-ui/dist/components/...`.
+
+## 7. Logo behavior
+
+In v2.0.0, pass an explicit `logo` prop to avoid a request to `/orbcafe.png`. The next v2 patch renders an offline package icon when `logo` is omitted. Pass `logo={null}` when the header should have no logo.
+
+## Verification checklist
+
+```bash
+npm ls orbcafe-ui react react-dom next tailwindcss
+npm run build
+```
+
+Then verify:
+
+- No install-time peer warnings remain.
+- Light, dark, and system modes stay synchronized with the host.
+- Navigation search, expand/collapse, routing, fixed/floating mode, and pin/unpin work.
+- Pinned items survive reload and do not split across page titles or locales.
+- No `/orbcafe.png` 404 or `ERR_PACKAGE_PATH_NOT_EXPORTED` appears.
+- Standard report, dialogs, date fields, charts, Kanban, Planning, and AgentUI receive complete styles.
+- Browser console and server logs are clean during SSR and hydration.
+
+## Rollback
+
+If the application cannot complete the migration in the current release window, pin the previous major explicitly and keep the lock file:
+
+```json
+{
+  "dependencies": {
+    "orbcafe-ui": "1.4.6"
+  }
+}
+```

package/README.md

@@ -41,6 +41,8 @@ The library is designed for two audiences at once:
 
 ## Install
 
+> Upgrading from v1? Version 2 is a breaking MUI-to-ORBIS migration. Follow the [v2 migration guide](MIGRATION_V2.md) before changing a production dependency.
+
 Install the package. `orbcafe-ui@2` is **MUI-free** — the runtime dependencies (Radix primitives, `class-variance-authority`, `tailwind-merge`, `clsx`, `dayjs`, ...) ship with the package, so you do **not** need `@mui/*`, `@emotion/*`, or `lucide-react`:
 
 ```bash
@@ -53,6 +55,10 @@ Tailwind v4 is required to compile the utility classes used by the components:
 npm install -D tailwindcss @tailwindcss/postcss
 ```
 
+Brand theming is optional. The default ORBIS theme and packaged theme overrides
+work without Open Design; see [BRAND_THEMING.md](BRAND_THEMING.md) for built-in
+packs and the optional `orbcafe-theme` CLI workflow.
+
 ## Required App Setup
 
 ### Tailwind source scanning
@@ -73,17 +79,9 @@ When developing inside this repo, the examples app also scans the source package
 @source "../../src";
 ```
 
-Tailwind v3 fallback:
-
-```js
-module.exports = {
-  content: ["./node_modules/orbcafe-ui/dist/**/*.{js,mjs}"],
-};
-```
-
 ### Providers
 
-Wrap your app with the ORBCAFE providers used by the official examples. V2 is MUI-free — there is no MUI `ThemeProvider`/`CssBaseline`/`LocalizationProvider`:
+Mount `GlobalMessage` once at the application layer. Add `OrbisModeProvider` there when standalone ORBCAFE surfaces or the host design system share the same mode. V2 is MUI-free, so there is no ORBCAFE requirement for MUI `ThemeProvider`, `CssBaseline`, or `LocalizationProvider`:
 
 ```tsx
 'use client';
@@ -102,7 +100,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-> `CAppPageLayout` / `PAppPageLayout` already render `OrbisModeProvider` + `GlobalMessage` internally; the explicit providers above are only required for standalone surfaces (e.g. a login page without the app shell). Dark mode is applied automatically by toggling the `orb-dark` class on `<html>`.
+> `CAppPageLayout` / `PAppPageLayout` render their own `OrbisModeProvider`, but `GlobalMessage` must be mounted once by the host. `CAppPageLayout` supports controlled `mode` / `onModeChange` for synchronizing another design system. Dark mode is applied automatically by toggling the `orb-dark` class on `<html>`.
 
 ## Run The Official Examples