@cboxdk/cbox-ui 0.7.0 → 0.9.0

package/README.md

@@ -114,7 +114,7 @@ Match id's existing patterns — see id/resources/js/pages/* for examples.
 | `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). |
+| `CboxAppCatalog` | The Switch-app control fed live from the host's catalog endpoint: the shared `<cbox-app-switcher>` element (see "App catalog" below). |
 | `NotificationsBell` | Bell icon with unread badge, links to id's unified inbox. Renders nothing if context lacks `notifications`. |
 
 ### Page primitives
@@ -193,28 +193,82 @@ 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.
+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" icons={serviceMarks} />
+<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?, description? }], refresh_after?: seconds }`
+- `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. `icons` maps an app key to a mark the host bundles (the family's
-service marks); without one the catalog's `icon_url` is shown, then the name's initials.
+- `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)`.
 
 ### Workspace navigation (current design contract)
 

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 };