@bridge-ds/toolbar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Florian Gouloubi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @bridge-ds/toolbar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Bridge toolbar for a product built with the Bridge design system. Bridge Studio opens the product with
+`?bridge=<change>` ("Try it in the product"); the toolbar then lets anyone browse the real product and flip between
+**Live product** (before) and **This change** (after), with **Show what changed** for token changes.
+
+- **Code changes** (an exploration in the product's repository, a feature branch): Before is the product in
+  production, After is the branch's preview. Flipping keeps the screen and the scroll position.
+- **Token changes** of the design system: the live tokens swap in without a reload, and Show what changed outlines
+  every surface that differs.
+
+Without `?bridge=` (or the session that remembers it) it renders nothing and loads nothing: the toolbar and its styles
+are one lazy chunk.
+
+## Mount it
+
+```sh
+npm i @bridge-ds/toolbar
+```
+
+One line at the root of the app, inside the design system's `ThemeProvider`:
+
+```tsx
+import { BridgeToolbar } from '@bridge-ds/toolbar';
+
+<BridgeToolbar ds="acme/design-system" product="checkout" />
+```
+
+`ds` is the design system repository and `product` the product's key in its `bridge.config.json` `products[]`. When
+Studio opens the page, the toolbar reads that config from GitHub once per session: the product's repository (where its
+explorations are pull requests), `production` (Before of a code change), `preview` (the branch preview template, the
+only hosts allowed to hand over to production) and production Studio (`previews.production.docs`, the way back and the
+live tokens). `bridge connect` prints this line with your values.
+
+```json
+{ "key": "checkout", "name": "Checkout", "repo": "acme/checkout", "framework": "react",
+  "preview": "https://checkout-git-{branch}-acme.vercel.app", "production": "https://checkout.acme.com" }
+```
+
+## Options
+
+| Prop | What it does |
+| --- | --- |
+| `studio`, `production`, `preview` | Override what the config says (for example a staging URL as Before). |
+| `deployEnv` | `"production"` or `"preview"` when your build knows it (Vercel: `VERCEL_ENV`). |
+| `build` | Every fact at once, read at build time: no config read at run time. |
+| `scope` | A hook returning `{ theme, brand, density, shop, set }` when your app keeps theme and shop in state. Default: the `data-theme`, `data-brand` and `data-density` attributes `ThemeProvider asRoot` puts on `<html>`. |
+| `shops` | `{ id, name, brand }[]` of a multi-brand product, for the screens list and "Switch to <shop>". |
+| `together` | A loader of the latest library's token files (`togetherBase` from `@bridge-ds/toolbar/together`), so Studio's "Try them together" runs on your production. |
+
+Reads are anonymous (public repositories): at most a few GitHub API reads per change and session.

package/dist/BridgeToolbar.d.ts

@@ -0,0 +1,25 @@
+import { type BridgeBuild } from './session';
+import type { ToolbarScope, ToolbarShop } from './scope';
+import type { TogetherBase } from './together';
+export interface BridgeToolbarProps {
+    /** The design system repository, "owner/name". The toolbar reads its bridge.config.json when Studio opens the page. */
+    ds?: string;
+    /** This product's key in the design system's bridge.config.json products[] ("checkout"). */
+    product?: string;
+    /** Overrides of what the config says: production Studio, this product in production, its preview template. */
+    studio?: string | null;
+    production?: string | null;
+    preview?: string | null;
+    /** The deploy environment ("production", "preview"), when the host tells it at build time (VERCEL_ENV). */
+    deployEnv?: string | null;
+    /** Every fact at once, read at build time: no config read at run time (the Admin demo passes it). */
+    build?: BridgeBuild;
+    /** A hook that says where the page is and moves it (theme, shop). Default: the attributes ThemeProvider sets on <html>. */
+    scope?: () => ToolbarScope;
+    /** The shops of a multi-brand product, for the screens list and "Switch to <shop>". */
+    shops?: ToolbarShop[];
+    /** The latest library's token files as a combination base: lets Studio's "Try them together" run here. */
+    together?: () => Promise<TogetherBase>;
+}
+/** Mounted once at the app root. Without a change from Studio it renders nothing and loads nothing. */
+export declare function BridgeToolbar(props: BridgeToolbarProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/ChangeOutlines.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+import type { Theme } from '@bridge-ds/react';
+import { type ChangedElement } from './outline';
+import type { Rect } from './session';
+export interface Shown {
+    /** Visible surfaces, in order. */
+    count: number;
+    /** Boxes of the visible surfaces that are not page-sized: the toolbar keeps clear of them. */
+    obstacles: Rect[];
+}
+export declare function ChangeOutlines({ surfaces, theme, tip, onShown, emphasis, flash, }: {
+    surfaces: ChangedElement[];
+    theme: Theme;
+    /** The surface whose list row is hovered, focused or activated: chip and stronger outline. */
+    emphasis: number | null;
+    /** Show every chip (the moment outlines turn on). */
+    flash: boolean;
+    /** Tooltip content for a surface: its role, token and before and after. */
+    tip: (s: ChangedElement) => ReactNode;
+    onShown: (shown: Shown) => void;
+}): import("react/jsx-runtime").JSX.Element;