@cboxdk/cbox-ui 0.8.0 → 0.10.0

package/README.md

@@ -2,9 +2,9 @@
 
 Shared UI for the Cbox app family — id, cortex, atlas, track, and whatever's next.
 
-This package gives every Cbox app the same chrome (top bar, org switcher, app launcher, user menu, notifications bell) and the same page primitives (panels, headers, tabs, status pills) so cross-app navigation feels like one product. It also ships the design tokens (colours, fonts, radii) and the brand assets in one place.
+This package gives every Cbox app the same shell (`CboxShell`: rail, header with the context selectors, ⌘K palette, Help column, app switcher, account menu, phone layout) and the same page primitives (panels, headers, tabs, status pills), so moving between apps feels like one product. It also ships the design tokens (colours, fonts, radii) and the brand assets in one place.
 
-The package is **headless about data**: every component reads identity, organization, and notification state from a `<CboxIdProvider>` context that the consuming app populates from the future `@cboxdk/cbox-id-client` SDK. Components never fetch — they render what the host gave them.
+The shell renders one Inertia prop, `shell`, which the server builds (laravel-console-kit). The prop carries only the current selection and URLs; menus, the app catalog, Help and search load in the browser after the page has painted, from same-origin endpoints the app serves. See [The shell](#the-shell) and the spec in `docs/specs/2026-11-10-shell-v1.md`.
 
 ## Install
 
@@ -29,61 +29,40 @@ The package is published on npm as `@cboxdk/cbox-ui` under the MIT License. The
 
 That's it — every `text-foreground`, `bg-card`, `border-border`, `text-mono`, etc. utility now resolves against the Cbox palette. Light + dark variants come bundled: dark applies under `.dark` or `data-theme="dark"` on the root, whichever the host writes. Add `@source '../../node_modules/@cboxdk/cbox-ui/dist';` so Tailwind generates the utilities the components use, and when the host stores its theme choice as an attribute, point Tailwind's `dark:` variant at it (`@custom-variant dark (&:where([data-theme='dark'], [data-theme='dark'] *));`).
 
-### 2. Wrap the app root with `<CboxIdProvider>`
-
-In **id itself** (which IS the source of truth), populate from Inertia shared props:
+### 2. Render the shell in the persistent layout
 
 ```tsx
-import { CboxIdProvider } from '@cboxdk/cbox-ui';
+// resources/js/layouts/AppLayout.tsx
+import { router, usePage, Link } from '@inertiajs/react';
+import { CboxShell, type Shell } from '@cboxdk/cbox-ui';
 
-export default function AppRoot({ shared, children }) {
+export default function AppLayout({ children }: { children: React.ReactNode }) {
+    const { shell } = usePage<{ shell: Shell }>().props;
     return (
-        <CboxIdProvider value={shared.cboxId}>
+        <CboxShell
+            shell={shell}
+            LinkComponent={Link}
+            navigate={(url, o) => (o?.newTab ? window.open(url, '_blank', 'noopener') : router.visit(url, { method: o?.method, data: o?.data }))}
+            onPreferenceChange={(key, value) => router.post('/settings/shell', { [key]: value }, { preserveState: true, preserveScroll: true })}
+        >
             {children}
-        </CboxIdProvider>
+        </CboxShell>
     );
 }
-```
-
-In **cortex / atlas / track / future apps**, populate from the id-client SDK on session start:
-
-```tsx
-import { CboxIdProvider } from '@cboxdk/cbox-ui';
-import { useIdSession } from '@cboxdk/cbox-id-client';
 
-export default function AppRoot({ children }) {
-    const session = useIdSession(); // {user, organizations, currentOrg, ...}
-    return (
-        <CboxIdProvider value={session.cboxIdContext}>
-            {children}
-        </CboxIdProvider>
-    );
-}
+// Every page: `Page.layout = page => <AppLayout>{page}</AppLayout>`, so the rail, Help and the
+// chat stay mounted between visits.
 ```
 
-The context shape is exported as `CboxIdContextValue` — see `src/context/cbox-id.tsx` for the full surface. Required keys:
+Set the theme before the first paint: the server writes `class="dark"` and `data-theme` on
+`<html>` from `shell.preferences.theme`, or the head carries the inline script
+`themeBootScript(theme)` returns (it resolves `system` from the device without saving it).
+Copy `public/brand/` (the Cbox wordmark: `cbox-logo.png`, `cbox-logo-white.png` and their `@2x`)
+as before; `brandAssetBase` changes the path.
 
-- `user` — `{id, name, email, avatar_url?, locale?, timezone?}`
-- `currentOrganization` — current org context (or null on user-only surfaces)
-- `organizations` — every org the user belongs to (drives the switcher)
-- `apps` — sister apps for the launcher
-- `urls` — `{idBaseUrl, accountUrl, orgSettingsUrl, switchOrgUrl, signOutUrl}`
-- `notifications?` — `{unreadCount, inboxUrl}` (optional, hides the bell when missing)
-- `onSwitchOrganization?` — callback when the user picks an org (default: form-POST to `urls.switchOrgUrl`)
+### 3. Identity context (inbox only)
 
-### 3. Drop in the chrome
-
-```tsx
-import { TopBar } from '@cboxdk/cbox-ui';
-
-<TopBar
-    brand={<MyAppLogo />}
-    centre={<MySearchBar />}
-    showOrgSwitcher
-/>
-```
-
-The default right-cluster is `<AppLauncher>` → `<NotificationsBell>` → `<UserMenu>`. Override with `rightCluster={...}` if a particular app needs a different mix.
+`<CboxIdProvider>` still feeds the inbox surface (`CboxSurfaces`). The shell does not read it.
 
 ### 4. Use page primitives
 
@@ -106,16 +85,15 @@ Match id's existing patterns — see id/resources/js/pages/* for examples.
 
 ## Components
 
-### Chrome (cross-app navigation)
+### Shell
 
-| Component | What it does |
+| Export | What it does |
 |---|---|
-| `TopBar` | Standard 56px-tall app bar. Slot for brand + centre + right cluster. |
-| `OrgSwitcher` | Dropdown listing the user's orgs. Calls `onSwitchOrganization` (or POSTs to `urls.switchOrgUrl`) on pick. |
-| `AppLauncher` | 9-dot grid showing sister Cbox apps the user can jump into. |
-| `UserMenu` | Avatar dropdown with "Manage account ↗" + "Team & billing ↗" (deep-links into id) + Sign out. Pass `LinkComponent` when those rows are pages of the host app, so the visit stays client-side. |
-| `CboxAppCatalog` | The Switch-app control fed live from the host's catalog endpoint (see "App catalog" below). |
-| `NotificationsBell` | Bell icon with unread badge, links to id's unified inbox. Renders nothing if context lacks `notifications`. |
+| `CboxShell` | The one shell for every app, rendered from the `shell` prop. See [The shell](#the-shell). |
+| `Shell`, `ContextLevel`, `ContextItem`, `NavArea`, `PaletteAction`, … | The prop's TypeScript contract (spec §11.1). laravel-console-kit produces it. |
+| `useShellHelp()` | `toggleHelp`, `openArticle`, `ask` for a page's own `?` button. |
+| `applyTheme`, `themeBootScript` | Put a theme choice on the document the way the tokens read it. |
+| `CboxAppCatalog` | The framework-free `<cbox-app-switcher>` element in React. Kept for apps that have not moved to the shell yet. |
 
 ### Page primitives
 
@@ -175,7 +153,7 @@ no provider is present. The host owns the selected language and its catalogs:
 
 ```tsx
 <CboxLocalizationProvider locale={language} translate={t}>
-    <CboxAppShell {...shellProps}>{children}</CboxAppShell>
+    <CboxShell shell={shell}>{children}</CboxShell>
 </CboxLocalizationProvider>
 ```
 
@@ -193,60 +171,211 @@ callback; without it, existing browser formatting is preserved.
 
 ### App catalog (Switch app)
 
-`AppSwitcher` and `AppLauncher` render the static `apps` list from `CboxIdProvider`. Apps
-that read the person's catalog live from Cbox ID use `CboxAppCatalog` instead: the host
-serves a same-origin endpoint (a proxy of Cbox ID's catalog under the signed-in person's
-grant) and the component renders its answer, refreshes it when `refresh_after` expires
-while the panel is open, and offers the way back to Cbox ID when the grant is missing.
+The shell's own app grid reads the same endpoint (see [The shell](#the-shell)). The element below stays for apps that have not moved to the shell yet.
+
+Every Cbox app, Blade or React, draws the same Switch-app control: the `<cbox-app-switcher>`
+custom element from `@cboxdk/cbox-ui/app-switcher`. It has no React dependency and renders
+in a shadow root with its own styles, so no app stylesheet (a reset, a missing preflight, a
+global `button`, `img` or `svg` rule) changes how it looks. It takes only the host's Cbox
+colour tokens (`--foreground`, `--popover`, `--border`, `--secondary`, `--muted`,
+`--accent-soft`, `--ring`), each with a fallback.
+
+**Blade (or any server-rendered page).** Import the module once in the app's Vite entry
+(`resources/js/app.js`):
+
+```js
+import '@cboxdk/cbox-ui/app-switcher';
+```
+
+and put the tags in the layout:
+
+```blade
+<cbox-app-switcher
+    endpoint="{{ $appCatalogUrl ?? '' }}"
+    current="billing"
+    labels="{{ json_encode(['title' => __('Switch app'), 'loading' => __('Loading apps…'), 'empty' => __('No apps available'), 'unavailable' => __('Apps could not be loaded.')], JSON_UNESCAPED_UNICODE) }}"
+></cbox-app-switcher>
+
+{{-- The app's own mark (rail, brand), from the same catalog --}}
+<cbox-service-mark service="billing" aria-hidden="true"></cbox-service-mark>
+```
+
+**React.** `CboxAppCatalog` renders the same element:
 
 ```tsx
 <CboxAppCatalog endpoint={appCatalogUrl} currentAppKey="infra" />
 ```
 
-The endpoint contract (`parseAppCatalog` is exported, so a host can test its own answer):
+Attributes of `<cbox-app-switcher>`:
+
+| Attribute | |
+|---|---|
+| `endpoint` | The host's same-origin catalog URL. Empty disables the control (pages without an organization). Another origin is refused. |
+| `current` | This app's key: its tile is marked current. |
+| `labels` | JSON with any of `title`, `loading`, `empty`, `unavailable`. Missing keys stay English. |
+| `theme` | `auto` (default): `.dark`/`[data-theme="dark"]` or `.light`/`[data-theme="light"]` on `<html>`, else `prefers-color-scheme`. `class`: only the root marker counts, no marker is light (a host whose tokens only turn dark under `.dark`). `light`/`dark` pin it. |
+
+`<cbox-service-mark service="key">` paints that app's icon from the catalog this browser last
+kept, and repaints when a newer one arrives. It is 24px; set
+`cbox-service-mark { --cbox-service-mark-size: 22px; }` to change it. It takes `theme` too.
+
+The endpoint contract (`parseAppCatalog` and `signInTarget` are exported, so a host can test
+its own answer):
 
 - `200 { apps: [{ key, name, launch_url, icon_url?, icon_dark_url?, description? }], refresh_after?: seconds }`
   — `refresh_after` is clamped to 1–60 s; apps without an `http(s)` launch URL are dropped.
-- `401`/`403` with `{ authorize_url }` or `{ state: 'authorization_required' }` — the panel
-  says the apps could not be loaded and links "Reconnect to Cbox ID" to `authorize_url` with
-  `return_to` set to the current path (same-origin URLs only).
-- Anything else — "Apps could not be loaded." with a retry.
-
-`endpoint={null}` renders the control disabled, so the chrome keeps its shape on pages
-without an organization.
-
-App icons come from Cbox ID's catalog: `icon_url` for light surfaces and `icon_dark_url` for
-dark ones. The tiles render both and the token stylesheet shows the one for the current theme
-(`.dark` or `[data-theme="dark"]` on the root); an app without an icon shows its initials. Apps
-keep no local copy of the marks. Each answer is kept in this browser (`cbox-app-catalog`), so
-`<CboxServiceMark appKey="infra" />` and the collapsed `CboxBrand` in the rail paint the app's
-own icon at once on the next page. A host that loads the catalog itself calls
-`rememberAppCatalog(apps)`; `CboxAppIcon` renders any single app's icon.
-
-### Workspace navigation (current design contract)
-
-`CboxWorkspaceShell` is the two-tier product shell. Pass `areas` (each has a
-label, href, icon and optional child `items`), the router's `currentPath` and
-`LinkComponent`, plus `context`, `tools` and `account` slots. Include the real
-organization context, search, notifications and Switch app in these slots;
-render `UserMenu placement="top-start"` in `account`. The account stays at the
-bottom of the main rail. Existing `CboxAppShell` consumers retain their API.
-
-The rail reserves 64px, expands on hover/focus without moving content, and
-reserves 222px when pinned. Context navigation only appears for multi-page
-areas; its panel button and Command/Control-period collapse it to a 26px strip.
-Mobile uses a modal navigation sheet and retains the header app switcher.
-Query strings do not change active navigation, and the **most specific href wins**: an
-area at the organization root (`/acme`) does not claim `/acme/projects/...` when a
-Projects area exists, and inside a subnav only the deepest matching item is active. Active
-links carry `aria-current="page"`.
-
-Hosts own route construction, organization switching, search and preference persistence.
-For the two shell preferences the host persists, pass them in: `pinned` + `onPinnedChange`
-and `collapsed` + `onCollapsedChange` (controlled), or `defaultPinned` / `defaultCollapsed`
-to seed the shell's own state. `brandHref` points the brand row somewhere other than `/`
-(the current organization's overview), and `mainId` names the `<main>` landmark for the
-host's skip link (default `main-content`).
+- `401`/`403 { signin_url }` — the person has to sign in again. When they open the control
+  (or it is open when the answer arrives), the element sends the top window to `signin_url`:
+  no message, no button. A page that merely loads in the background is never moved. If the
+  same sign-in was tried in the last 30 seconds and the catalog still refuses, it shows "Apps
+  could not be loaded." instead, so it never loops. The legacy `{ authorize_url }` is followed
+  the same way, with `return_to` set to the current path (same-origin URLs only).
+  `signin_url` must be on the app's own origin; anything else is ignored.
+- Anything else, or no network — "Apps could not be loaded.", quietly, and it tries again by
+  itself (2 s, 4 s, 8 s … up to 60 s). A grid it already shows stays.
+
+Before navigating it fires `cbox-app-switcher:signin` (bubbling, composed, cancelable, with
+`detail.url`); `preventDefault()` keeps the page where it is.
+
+App icons come from Cbox ID's catalog only: `icon_url` for light surfaces and
+`icon_dark_url` for dark ones; the element swaps them with the theme. Only `https:` icons
+render; an app without one, or whose icon fails to load, shows its initials. Apps keep no
+local copy of the marks. Each answer is kept in this browser (`localStorage`,
+`cbox-app-catalog`), so the grid and the marks paint at once on the next page and the live
+answer replaces them. The icons are served by Cbox ID, so the host's CSP needs
+`img-src https://cbox.cboxid.com` (the element's styles are constructed stylesheets, which
+`style-src` does not govern).
+
+In React, `<CboxServiceMark appKey="infra" />` and the collapsed `CboxBrand` read the same
+kept catalog; `CboxAppIcon` renders any single app's icon, and a host that loads the catalog
+itself calls `rememberAppCatalog(apps)`.
+
+## The shell
+
+`CboxShell` is the one shell for every Cbox app (spec: `docs/specs/2026-11-10-shell-v1.md`).
+The app passes the `shell` prop and the page; the shell does the rest.
+
+```
+┌──────┬────────────────────────────────────────────────────────────────────┬──────────┐
+│ rail │ [C] Cbox ⇕ / [W] Webshop · ■ Production ⇕   [Search or ask… ⌘K] [Help²] [🔔] [⣿] │ Help     │
+│      ├────────────────────────────────────────────────────────────────────┤ (docked  │
+│ areas│ sandbox strip (only while the environment has test data)           │ ≥1280px) │
+│ …    │ subnav │ page                                                      │          │
+│ [SD] │        │                                                           │          │
+└──────┴────────┴───────────────────────────────────────────────────────────┴──────────┘
+```
+
+### The `shell` prop
+
+The types are exported (`Shell`, `ContextLevel`, `ContextItem`, `NavArea`, `NavPage`,
+`PaletteAction`, `ShellHelp`, `ShellPreferences`, …) and are the contract laravel-console-kit
+produces. Abridged:
+
+```ts
+type Shell = {
+    app: { key; name; homeUrl };
+    person: { id; name; initials; avatarUrl? };
+    page?: { title; route? };                       // "On this page" and the chat's page intent
+    nav: { areas: NavArea[]; activeArea; activePage? };
+    context: { levels: ContextLevel[]; switchUrl };  // 1–3 levels, organization first
+    palette: { searchUrl?; gotoUrl?; actions: PaletteAction[] };
+    help: { enabled; topic?; sessionUrl?; scriptUrl?; portalUrl?; updatesUrl?; searchUrl?; articlesUrl? };
+    notifications: { enabled: false } | { enabled: true; unread; url };
+    apps: { catalogUrl; productsUrl? };
+    account: { profileUrl; switchAccountUrl; signOutUrl; signOutMethod?; languages?; formats?; signedInWith? };
+    banner?: { kind: 'sandbox' | 'impersonation' | 'notice'; text; action? };
+    preferences: { theme; locale; railPinned; helpOpen; subnavCollapsed?; regionalFormat?; timeZone? };
+};
+```
+
+`ContextLevel.settingsUrl` is a URL template on the wire: `{id}` is replaced with the row's id
+(`/orgs/{id}/settings`). Nav and action icons are Lucide names (`"rocket"`, `"server"`); pass
+`icons` to `CboxShell` for others.
+
+### What the app serves (all same-origin JSON)
+
+| URL | Request | Answer |
+|---|---|---|
+| `level.listUrl` | `GET ?q=&parent=&cursor=&limit=` | `{ object: "list", data: ContextItem[], has_more, next_cursor }`. Loaded when a menu opens; every level below the first gets `parent`, the level above's id (projects of an organization, environments of a project). Answers are kept for the page and dropped when the context changes. |
+| `level.createUrl` | `POST { name, parent? }` | `{ id, detailsUrl }` (or `details_url`). The person lands on `detailsUrl`. A 422 shows its first error under the field. |
+| `account.switchAccountUrl` | A plain link (full page load) | Usually a redirect to Cbox ID's account chooser. |
+| `context.switchUrl` | `POST { <level key>: id, …, return_to }` (a form post through `navigate`) | A redirect: the same page in the new context, or that area's list for an entity page (§5.6). |
+| `palette.searchUrl` | `GET ?q=` | `{ data: [{ id, title, subtitle?, url }] }`, in the current context. |
+| `palette.gotoUrl` | `GET ?q=` | `{ data: [{ title, subtitle?, levels?: { organization, project, … }, url? }] }` across organizations. |
+| `apps.catalogUrl` | `GET` | The catalog below, plus `in_organization`, `admission_url`, `purpose` and `hue` per app. |
+| `help.updatesUrl` | `GET`; `POST {updatesUrl}/{id}/read` | `{ data: [{ id, kind: "ticket" \| "chat", title, excerpt?, at, unread, url? }] }` |
+| `help.searchUrl` | `GET ?q=&topic=` | `{ data: [{ id, title, excerpt?, body?, url?, source? }] }` |
+| `help.articlesUrl` | `GET` (template, `{topic}`) | The same shape; the first three are shown. |
+
+Every link the shell follows from these answers (`url`, `detailsUrl`) must be `http(s)://` or
+a `/path`; anything else is dropped. None of these may call another service synchronously (local first): organizations come from
+the app's mirror of Cbox ID, the catalog from a cached copy. Help and docs search are proxies of
+Cbox Assistant served by laravel-assistant-client; when Assistant is down, Help says so and
+everything else works.
+
+Requests send `X-XSRF-TOKEN` (from the `XSRF-TOKEN` cookie) or `X-CSRF-TOKEN` (from
+`<meta name="csrf-token">`). Without a `navigate` prop, POSTs are real form submits with
+`_token`.
+
+### Preferences and first paint
+
+The shell reports every preference change through `onPreferenceChange(key, value)`: `theme`,
+`locale`, `regionalFormat`, `timeZone` (Cbox ID's shared preferences), and `railPinned`,
+`helpOpen`, `subnavCollapsed` (the app's cookie, read on the server). Without the callback it
+writes a `cbox_shell_<key>` cookie. The server sends them back in `shell.preferences`, so the
+rail, Help and the subnav render in place on the server; `themeBootScript(theme)` (or the same
+class and `data-theme` written by the server) sets the theme before paint.
+
+### Help
+
+Help is part of the shell: support updates (the button's count), docs and knowledge base
+search, articles for the page's `help.topic`, Ask Cbox, Talk to a person and the support portal.
+It docks beside the page from 1280px (360px, 400px from 1440px) and is a full-screen dialog
+below. Its state (open, article, search, scroll, updates) lives in a store outside React, so it
+survives visits and even a remount; the chat element sits outside the home/article view, so
+opening an article never ends the conversation, and it survives as long as the shell sits in
+the persistent layout. Help the person left open shows docked on load; below 1280px it waits
+until they open it, so a phone or a narrow window never lands under the overlay. Support
+updates are per organization: they load again when the organization or `updatesUrl` changes.
+Closing Help gives focus back to what opened it.
+
+The chat is the Assistant SDK's `<cbox-support session-url>` element (laravel-assistant-client,
+`/ai-assistant/support.js` by default, loaded the first time Help opens). The shell sets
+`element.intent = { route, title, context, url }` (and an `intent` JSON attribute) on every
+page, and calls `element.ask(question, intent)` / `element.handover()` when the SDK has them,
+else `element.open()`.
+
+A page's own `?` button uses `useShellHelp()?.toggleHelp()`, or `<PageHeader help />`. The page's
+help topic is `shell.help.topic`, set on the server per route (console-kit's `helpTopic`), not
+a prop of the header: Help needs it on the first paint and on pages without a header.
+
+### Keyboard
+
+⌘K / Ctrl+K opens the palette anywhere (↑↓ move, Enter opens, ⌘Enter opens in a new tab, Esc
+closes). In the context menus ↑↓ Home End move, Enter picks, → makes a row's gear the active
+option (Enter opens its settings; in the cascade a second → crosses to the environments), ←
+goes back, Esc closes and Tab leaves; focus returns to the trigger. ↓ past the last row
+reaches "New …" and ↑ above the first reaches "View all", so both work without a mouse; in the
+app grid End and ↓ from the bottom row reach "All products". ⌘. collapses the subnav. Search fields focus themselves only with a fine pointer and
+hover, never on touch. Sheets and the Help overlay trap focus; the docked column does not.
+
+### Phone (< 768px)
+
+The header holds ☰ (areas, pages, Switch app, notifications, the account), one context button
+(`Cbox / Webshop / Production`) that opens every level stacked, Search and Help (full screen).
+Nothing is hidden without a replacement.
+
+### Tests and snapshots
+
+`bun run test` runs the unit tests (vitest, Testing Library, happy-dom). `bun run test:visual`
+renders the fixture page in `tests/visual` (the real shell, the fixture `shell` prop and its
+answers) and compares every open state at 1440 and 390, light and dark, against
+`tests/visual/__screenshots__`, and runs axe on every open state. It runs in the pinned
+Playwright container (`scripts/visual.sh`, needs Docker), the same one CI's `visual` job uses,
+so the Linux baselines match pixel for pixel. After an intended change:
+`bun run test:visual:update`, then look at every changed image.
+
+### Tokens
 
 Core tokens now match the warm cream/ink design-system colors. Body text uses
 the system stack; hosts self-host Plus Jakarta Sans for headings and JetBrains

package/dist/app-switcher.d.ts

@@ -0,0 +1,19 @@
+export { b as CboxAppCatalogState, c as CboxCatalogApp, a as CboxKnownApp, C as CboxThemeMode, d as authorizeHref, i as isDark, p as parseAppCatalog, r as readKnownAppCatalog, e as rememberAppCatalog, s as secureIconUrl, f as signInTarget, g as subscribeKnownAppCatalog } from './catalog-BroZWvws.js';
+
+/** The words the control shows. Pass a translation as the `labels` attribute (JSON). */
+type CboxAppSwitcherLabels = {
+    title: string;
+    loading: string;
+    empty: string;
+    unavailable: string;
+};
+declare const DEFAULT_LABELS: CboxAppSwitcherLabels;
+/**
+ * Fired on `<cbox-app-switcher>` (bubbling, composed, cancelable) just before it sends the
+ * person to sign in again; `detail.url` is where. `preventDefault()` keeps the page where it is.
+ */
+declare const SIGNIN_EVENT = "cbox-app-switcher:signin";
+/** Define `<cbox-app-switcher>` and `<cbox-service-mark>` once. A no-op outside a browser. */
+declare function defineCboxAppSwitcher(): void;
+
+export { type CboxAppSwitcherLabels, DEFAULT_LABELS, SIGNIN_EVENT, defineCboxAppSwitcher };

package/dist/app-switcher.js

@@ -0,0 +1,7 @@
+import { defineCboxAppSwitcher } from './chunk-AJCYF7SS.js';
+export { DEFAULT_LABELS, SIGNIN_EVENT, authorizeHref, defineCboxAppSwitcher, isDark, parseAppCatalog, readKnownAppCatalog, rememberAppCatalog, secureIconUrl, signInTarget, subscribeKnownAppCatalog } from './chunk-AJCYF7SS.js';
+
+// src/app-switcher/index.ts
+defineCboxAppSwitcher();
+//# sourceMappingURL=app-switcher.js.map
+//# sourceMappingURL=app-switcher.js.map

package/dist/app-switcher.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/app-switcher/index.ts"],"names":[],"mappings":";;;;AAcA,qBAAA,EAAsB","file":"app-switcher.js","sourcesContent":["/**\n * `@cboxdk/cbox-ui/app-switcher` — the one Switch-app control for every Cbox app, framework\n * free. Importing this module defines `<cbox-app-switcher>` and `<cbox-service-mark>`:\n *\n *     import '@cboxdk/cbox-ui/app-switcher';\n *\n *     <cbox-app-switcher endpoint=\"/acme/apps/catalog\" current=\"billing\"\n *         labels='{\"title\":\"Skift app\"}'></cbox-app-switcher>\n *     <cbox-service-mark service=\"billing\" aria-hidden=\"true\"></cbox-service-mark>\n *\n * Both render in a shadow root with their own styles, so no app stylesheet changes them.\n */\nimport { defineCboxAppSwitcher } from './elements';\n\ndefineCboxAppSwitcher();\n\nexport { defineCboxAppSwitcher, DEFAULT_LABELS, SIGNIN_EVENT, type CboxAppSwitcherLabels } from './elements';\nexport {\n    authorizeHref,\n    parseAppCatalog,\n    readKnownAppCatalog,\n    rememberAppCatalog,\n    secureIconUrl,\n    signInTarget,\n    subscribeKnownAppCatalog,\n    type CboxAppCatalogState,\n    type CboxCatalogApp,\n    type CboxKnownApp,\n} from './catalog';\nexport { isDark, type CboxThemeMode } from './theme';\n"]}

package/dist/catalog-BroZWvws.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Which theme the host page shows, read the way every Cbox app marks it:
+ *
+ * - `.dark` or `[data-theme="dark"]` on the root element: dark;
+ * - `.light` or `[data-theme="light"]` on the root element: light;
+ * - neither: the system's `prefers-color-scheme`, unless the element says `theme="class"`
+ *   (a host whose tokens only turn dark under `.dark`, so no marker means light).
+ *
+ * `theme="light"` or `theme="dark"` on the element pins it.
+ */
+type CboxThemeMode = 'auto' | 'class' | 'light' | 'dark';
+declare function isDark(mode?: CboxThemeMode): boolean;
+
+/**
+ * The app catalog contract every Cbox app serves, and the copy of it this browser keeps.
+ * Framework-free: the `<cbox-app-switcher>` element and the React components both read it.
+ *
+ * Every app's icon comes from Cbox ID's catalog: one light and one dark upload per app
+ * (`icon_url`, `icon_dark_url`). No app keeps a local copy of the marks.
+ */
+/** One app as the host's catalog endpoint lists it. */
+type CboxCatalogApp = {
+    key: string;
+    name: string;
+    launch_url: string;
+    /** Cbox ID's uploaded icon for light surfaces. */
+    icon_url?: string | null;
+    /** Cbox ID's uploaded icon for dark surfaces. */
+    icon_dark_url?: string | null;
+    description?: string | null;
+};
+type CboxAppCatalogState = {
+    status: 'idle' | 'loading';
+} | {
+    status: 'ready';
+    apps: CboxCatalogApp[];
+    refreshAfter: number;
+}
+/**
+ * The person has to sign in again. `signinUrl` is the new contract (the host's `401
+ * { signin_url }`), `authorizeUrl` the legacy one (`{ authorize_url }`).
+ */
+ | {
+    status: 'signin_required';
+    signinUrl: string | null;
+    authorizeUrl: string | null;
+} | {
+    status: 'unavailable';
+};
+/** One app as this browser keeps it between pages. */
+type CboxKnownApp = {
+    key: string;
+    name: string;
+    icon_url: string | null;
+    icon_dark_url: string | null;
+    launch_url?: string;
+};
+/**
+ * Interpret the catalog endpoint's answer:
+ *
+ * - `200 { apps: [{ key, name, launch_url, icon_url?, icon_dark_url?, description? }], refresh_after?: seconds }`
+ * - `401`/`403 { signin_url }`: the person signs in again there. The legacy `{ authorize_url }`
+ *   and `{ state: 'authorization_required' }` mean the same.
+ * - anything else: unavailable right now.
+ *
+ * Only `http(s)` launch URLs are kept: the tiles are links the person will click.
+ */
+declare function parseAppCatalog(ok: boolean, body: unknown): CboxAppCatalogState;
+type Here = {
+    origin: string;
+    pathname: string;
+    search: string;
+};
+/** The legacy authorize link with `return_to` set to where the person is, on this origin only. */
+declare function authorizeHref(authorizeUrl: string | null, location: Here): string | null;
+/**
+ * Where to send the person when the catalog says they must sign in again: the host's
+ * `signin_url` when it is on this origin (the app's own sign-in; never another site), else the legacy authorize
+ * link with `return_to`. `null` when neither is usable.
+ */
+declare function signInTarget(state: {
+    signinUrl: string | null;
+    authorizeUrl: string | null;
+}, location: Here): string | null;
+/** Only `https:` icon URLs are rendered: the icons are hosted by Cbox ID. */
+declare function secureIconUrl(url: unknown): string | null;
+/** The last catalog this browser kept (`localStorage` key `cbox-app-catalog`); empty without one. */
+declare function readKnownAppCatalog(): CboxKnownApp[];
+/** Keep the catalog the person just loaded, and tell every mark on this page to repaint. */
+declare function rememberAppCatalog(apps: ReadonlyArray<{
+    key: string;
+    name: string;
+    launch_url?: string | null;
+    icon_url?: string | null;
+    icon_dark_url?: string | null;
+}>): void;
+/** Call `change` whenever the kept catalog changes, on this page or in another tab. */
+declare function subscribeKnownAppCatalog(change: () => void): () => void;
+
+export { type CboxThemeMode as C, type CboxKnownApp as a, type CboxAppCatalogState as b, type CboxCatalogApp as c, authorizeHref as d, rememberAppCatalog as e, signInTarget as f, subscribeKnownAppCatalog as g, isDark as i, parseAppCatalog as p, readKnownAppCatalog as r, secureIconUrl as s };