@bridge-ds/core 0.18.0 → 0.19.0

package/dist/node/measure-script.d.ts

@@ -0,0 +1 @@
+export declare const MEASURE_SCRIPT: string;

package/dist/node/measure.d.ts

@@ -0,0 +1,212 @@
+import type { SpecLayout } from '../component-spec';
+import { type MeasuredBox, type MeasuredNode, type MeasuredProps, type MeasuredSpec, type MeasuredState, type MeasuredTokens } from '../measured-spec';
+import { type StorybookIframeOptions, type StorybookIndex } from '../storybook';
+import { MEASURE_SCRIPT } from './measure-script';
+import { GLOBALS_SCRIPT, TOKENS_SCRIPT } from './tokens-script';
+export { MEASURE_SCRIPT, TOKENS_SCRIPT, GLOBALS_SCRIPT };
+export * from '../measured-spec';
+/** The script's answer for one page. */
+export interface MeasureResult {
+    root: MeasuredNode | null;
+    /** Visible elements outside the story root (popups portaled to the body), up to 3. */
+    portals: MeasuredNode[];
+    /** Plain wrapper elements skipped above the root (decorators). */
+    wrappers: number;
+    nodes: number;
+    /** Style rules read, and stylesheets that could not be read (cross-origin). */
+    rules: number;
+    sheets: {
+        read: number;
+        blocked: number;
+    };
+    /** Custom properties in scope at the component (root and provider elements), the pool `matched` tokens come from. */
+    rootVariables: number;
+    /** Of those, the ones a provider element around the story defines, not the page root (Fluent's FluentProvider). */
+    scopedVariables?: number | undefined;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** The root is block-level and spans its container (or is width: 100%): it fills in Figma, it does not hug. */
+    rootFill?: boolean | undefined;
+    /** A filling root was laid out at this width (px) for the measure and its screenshot, not the canvas width. */
+    fillWidth?: number | undefined;
+    /** With `open`: how the popup came to show (`already`: the story renders it open), or `none`. */
+    opened?: 'already' | 'click' | 'hover' | 'focus' | 'none' | undefined;
+    error?: string | undefined;
+}
+export interface MeasuredStory extends MeasureResult {
+    /** With `shot`: the PNG written and the root's size in CSS pixels. */
+    shot?: {
+        file: string;
+        width: number;
+        height: number;
+    } | undefined;
+    /** The props the story rendered with, read from Storybook's story context (args over component defaults). */
+    props?: MeasuredProps | undefined;
+    /** The pseudo state forced on the component, when asked and the browser could force it. */
+    state?: MeasuredState | undefined;
+    id: string;
+    url: string;
+    /** Milliseconds from navigation to measured. */
+    ms: number;
+}
+/** The browser a measure runs in: a page that can open a URL and evaluate an expression (playwright's Page fits). */
+export interface MeasurePage {
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+        timeout?: number;
+    }): Promise<unknown>;
+    evaluate<T>(expression: string): Promise<T>;
+    /**
+     * Forces pseudo classes on every element matching `selector` (Chrome DevTools CSS.forcePseudoState), or clears
+     * them with []. Optional: without it, `state` is not measured.
+     */
+    forcePseudo?(selector: string, states: string[]): Promise<boolean>;
+    /** PNG of the first element matching `selector`, written to `file`; its size in CSS pixels. Optional (shots). */
+    screenshot?(selector: string, file: string): Promise<{
+        width: number;
+        height: number;
+    } | null>;
+}
+/**
+ * Tags the element a measure with these options reads (`data-bridge-measure-root`): the component after wrappers, the
+ * popup, or the `within` part. For a screenshot of exactly what was measured.
+ */
+export declare function markMeasuredRoot(page: MeasurePage, o?: Pick<MeasureOptions, 'root' | 'unwrap' | 'within' | 'target' | 'open'>): Promise<boolean>;
+export interface MeasureOptions {
+    iframe?: StorybookIframeOptions | undefined;
+    /** Root selector inside the iframe (`#storybook-root, #root`: Storybook 7+ then 6). */
+    root?: string | undefined;
+    maxNodes?: number | undefined;
+    maxDepth?: number | undefined;
+    /** Longest wait for the story to render, ms (default 15000). */
+    timeout?: number | undefined;
+    /**
+     * Measure the open popup (a menu, a dialog, a select's list, a tooltip) instead of its trigger: when none shows yet,
+     * the first closed trigger in the story is clicked, then hovered and focused, and the popup portaled to the body is
+     * the measured root. Stories that render open (`defaultOpen` / `open` args) are measured as they are.
+     */
+    open?: boolean | undefined;
+    /**
+     * A part measured alone inside what rendered (the component, then its popups): `[role=menuitem]`, `[role=tab]`, a
+     * class. For parts that only render inside a parent or a portal (a menu item, an accordion item, a toast).
+     */
+    within?: string | undefined;
+    /** Story args to render with (`{ size: 'lg', disabled: true }`), passed in the iframe URL. */
+    args?: Record<string, string | number | boolean> | undefined;
+    /** A pseudo state forced on the component before it is measured (needs `MeasurePage.forcePseudo`). */
+    state?: MeasuredState | undefined;
+    /** Read the story's props from Storybook (default true in measureStory). */
+    props?: boolean | undefined;
+    /** Width a filling root is laid out at when it spans the canvas (default 400 px; 0 keeps the canvas width). */
+    fillWidth?: number | undefined;
+    /** Write a PNG of the measured root to this file (needs `MeasurePage.screenshot`), forced state included. */
+    shot?: string | undefined;
+    /** `portal`: the newest popup outside the story root is the component (set by `open`). */
+    target?: 'root' | 'portal' | undefined;
+    /**
+     * Go down from the root through plain wrappers and viewport-size decorator canvases to the component (default true).
+     * false: the root element is the component.
+     */
+    unwrap?: boolean | undefined;
+}
+/**
+ * Waits until the story has rendered: Storybook's root has content (or its error screen shows), fonts are loaded and
+ * the markup stops changing for a few frames. Resolves with `rendered`, `error` or `timeout`.
+ */
+export declare const WAIT_SCRIPT: (rootSel: string, timeout: number, self?: boolean) => string;
+/**
+ * Opens the story's popup when none shows: clicks the first closed trigger (pointer and mouse events in order), then
+ * hovers and focuses it (tooltips), and waits for the portal to settle. Resolves with how it opened, or `none`.
+ */
+export declare const OPEN_SCRIPT: (rootSel: string) => string;
+/**
+ * Reads the rendered story's props from Storybook's preview (7, 8, 9): its args (with URL overrides) over the component
+ * defaults docgen found, and the argTypes (enum options, booleans, texts). Plain values only; null when the preview
+ * exposes nothing.
+ */
+export declare const PROPS_SCRIPT: (id?: string) => string;
+/**
+ * Token values as the open story resolves them (on the component, so provider-scoped variables count): token path ->
+ * computed value, colors as `rgb()` and lengths in px, for value-level comparison (compareSpecToMeasured's `resolve`).
+ */
+export declare function resolveTokenValues(page: MeasurePage, vars: Record<string, string>): Promise<Record<string, string>>;
+export interface HarvestOptions {
+    iframe?: StorybookIframeOptions | undefined;
+    /** Read every mode the Storybook's globals expose (default true). */
+    modes?: boolean | undefined;
+    timeout?: number | undefined;
+}
+/**
+ * Every CSS custom property a Storybook's stylesheets define, read in one story: its declared value where the story
+ * sits (providers included), resolved there, in two tiers (a literal is a primitive, `var(--x)` is semantic), and again
+ * under each theme, brand or density global the Storybook exposes (one Figma mode per value).
+ */
+export declare function harvestTokens(page: MeasurePage, storybook: string, story: string, o?: HarvestOptions): Promise<MeasuredTokens>;
+/**
+ * Makes sure the story renders with these args. Storybook drops URL args it cannot validate against a story's initial
+ * args (Carbon's Button story declares none), so when the store does not hold them after the first render they are
+ * sent the way the Controls panel sends them (`updateStoryArgs`), and the re-render is awaited. Resolves `url` (the URL
+ * args held), `channel`, or `failed`.
+ */
+export declare const APPLY_ARGS_SCRIPT: (id: string, args: Record<string, string | number | boolean>, timeout: number) => string;
+/** Opens one story in its iframe and measures what it rendered. */
+export declare function measureStory(page: MeasurePage, storybook: string, id: string, o?: MeasureOptions): Promise<MeasuredStory>;
+/** Measures what the page shows now (a story already open, or re-rendered with new args): waits for it, then reads it. */
+export declare function measureRendered(page: MeasurePage, o?: MeasureOptions): Promise<MeasureResult & {
+    ms: number;
+    state?: MeasuredState | undefined;
+    shot?: {
+        file: string;
+        width: number;
+        height: number;
+    } | undefined;
+}>;
+export interface StoryPick {
+    id: string;
+    title: string;
+    name: string;
+}
+export interface PickStoriesOptions {
+    /** Components by name or title, case-insensitive ("Button", "Forms/Input"). */
+    only?: string[] | undefined;
+    /** Exact story ids; replaces `only` and `perComponent`. */
+    ids?: string[] | undefined;
+    /** Stories per component, in index order (default 3). */
+    perComponent?: number | undefined;
+}
+/** The stories a measure opens: given ids, else the first stories of each (selected) component. */
+export declare function pickStoriesToMeasure(index: StorybookIndex, o?: PickStoriesOptions): StoryPick[];
+/**
+ * The instances of a story that renders a component several times (a "Sizes" story, a row of tags, a matrix table of
+ * colors by sizes): under layout-only frames, captions aside, the components found, when most are the same component.
+ * Returns [] for a story that renders one component: a radio group's radios are its own parts (the group has a role,
+ * so it is the component, not a layout).
+ */
+export declare function splitInstances(root: MeasuredNode | null): MeasuredNode[];
+export interface MeasuredToSpecOptions {
+    /** CSS custom property -> token path. Default: the name without `--`, dashes as dots (`--space-2` -> `space.2`); private names (`--_bg`) are not tokens. */
+    tokenOf?: ((cssVar: string) => string | undefined) | undefined;
+}
+/**
+ * CSS module local name from a built class: Vite (`_label_aukrr_131`, `_label_1x2y3`), webpack and Next
+ * (`Button_label__a1b2c`, `Button-module__label__a1b2c`), a prefixed scheme (`prc-Button-Label-pTQ3x`). Other classes come
+ * back as they are.
+ */
+export declare function localClassName(cls: string): string;
+/**
+ * A class that says how an element looks, not what it is: a utility (`flex`, `px-4`, `hover:bg-blue`, `w-[12px]`,
+ * `-mt-1`) or a class a CSS-in-JS library generated from the styles (`css-1g7m1fs`, `sc-bdVaJa`). It changes with the
+ * look from one variant to the next, so it never names or pairs a part: tag and position do. A BEM or semantic
+ * class (`cds--btn__label`, `chakra-alert__title`, a CSS module's `label`) still does.
+ */
+export declare function isUtilityClass(cls: string): boolean;
+export declare function measuredLayout(style: Record<string, string>, children?: MeasuredBox[]): SpecLayout | undefined;
+/**
+ * Turns a measured story into the spec shape: one part per drawn element (wrappers that draw nothing are kept as
+ * frames, text runs become text parts), values bound to the declared token when there is one.
+ */
+export declare function measuredToSpec(m: Pick<MeasuredStory, 'id' | 'root'> & {
+    rootFill?: boolean | undefined;
+}, o?: MeasuredToSpecOptions): MeasuredSpec;

package/dist/node/spec-css.d.ts

@@ -74,7 +74,15 @@ export declare const DEFAULT_STATE: CssState;
 export declare function splitTop(text: string, sep: string | RegExp): string[];
 /** Parses one complex selector ("a > .b:hover .c"). Throws on syntax it does not know. */
 export declare function parseSelector(text: string): Complex;
-/** Media queries a component in Figma is drawn under: a mouse (hover: hover), nothing else. */
+/**
+ * The viewport width a component in Figma is drawn for: the one Storybook renders the code images at
+ * (@bridge-ds/visual references, 1200 x 800). Width media queries are read against it.
+ */
+export declare const SPEC_VIEWPORT_WIDTH = 1200;
+/**
+ * Media queries a component in Figma is drawn under: a mouse (hover: hover), a screen, and a viewport
+ * SPEC_VIEWPORT_WIDTH wide (`min-width` and `max-width` in px, alone or joined with `and`). Nothing else.
+ */
 export declare function mediaApplies(query: string): boolean;
 /** Rules of one CSS module, in source order. `@media` blocks are kept only when they apply in Figma. */
 export declare function parseCssModule(module: string, text: string, startOrder?: number): {

package/dist/node/tokens-script.d.ts

@@ -0,0 +1,3 @@
+export declare const TOKENS_SCRIPT: string;
+/** The Storybook globals that switch a theme, a brand or a density, with their toolbar values and defaults. */
+export declare const GLOBALS_SCRIPT: string;

package/dist/pr-composer.d.ts

@@ -38,6 +38,11 @@ export interface PrInput {
         path: string;
         choice: 'figma' | 'edit' | 'main';
     }[];
+    /**
+     * Pushed from the Figma plugin: design-approved (docs/BUILD-REQUESTS.md), so the tier line says what happens next
+     * instead of the approvals. Off unless set (the plugin passes it for a push).
+     */
+    fromFigma?: boolean | undefined;
 }
 /** Where a token change comes from. The plugin, the CLI and the MCP server each pass their own. */
 export interface PrOrigin {

package/dist/previews.d.ts

@@ -177,5 +177,8 @@ export declare const previewLinksOf: (previews: BranchPreview[]) => {
     label: string;
     url: string;
 }[];
-/** True when every configured app has its URL and a finished build (ready or failed): polling can stop. */
+/**
+ * True when every configured app has a finished build: ready with its URL, or failed (a build Vercel refused, such as
+ * a rate limit, never gets a URL). Polling can stop.
+ */
 export declare const previewsSettled: (previews: BranchPreview[]) => boolean;