@bridge-ds/core 0.6.0 → 0.7.0

package/dist/component-spec.d.ts

@@ -171,6 +171,59 @@ export interface SpecVector {
     svg: string;
     strokes: SpecValue[];
 }
+/**
+ * A prototype trigger, Figma's names. ON_HOVER "While hovering" and ON_PRESS "While pressing" go back when the pointer
+ * leaves or lets go; ON_CLICK "On click" stays. A set with a Checked axis uses MOUSE_ENTER / MOUSE_LEAVE for hover, so a
+ * click that changes Checked is not undone when the pointer leaves.
+ */
+export type SpecTrigger = 'ON_HOVER' | 'ON_PRESS' | 'ON_CLICK' | 'MOUSE_ENTER' | 'MOUSE_LEAVE';
+/** Designer names of the triggers, as Figma's prototype panel shows them. */
+export declare const TRIGGER_LABELS: Record<SpecTrigger, string>;
+/** An easing Figma can play: linear, or a cubic bezier with the exact points of the code's curve. */
+export interface SpecEasing {
+    type: 'LINEAR' | 'CUSTOM_CUBIC_BEZIER';
+    /** CUSTOM_CUBIC_BEZIER: x1, y1, x2, y2. */
+    bezier?: [number, number, number, number] | undefined;
+}
+/** The code's CSS transition for one change, resolved from the motion tokens. Played with Smart animate. */
+export interface SpecTransition {
+    /** Milliseconds. */
+    duration: number;
+    /** Token behind the duration ("motion.duration.instant"), when it is one. */
+    durationToken?: string | undefined;
+    easing: SpecEasing;
+    /** Token behind the easing ("motion.easing.standard"), when it is one. */
+    easingToken?: string | undefined;
+    /** CSS properties the code animates in this change ("background-color"). */
+    properties: string[];
+    /** Why Figma plays it slightly differently from the code (one speed for parts that move at several), when it does. */
+    approximated?: string | undefined;
+}
+/**
+ * A prototype interaction between variants of the set, read from the CSS: on `trigger`, every variant whose `axis` is
+ * `from` changes to the variant with `to` instead (other axes kept). `variants` narrows it to those variant keys
+ * (variantKeyOf) when it does not apply to all of them. `transition` null: the code changes it instantly.
+ */
+export interface SpecInteraction {
+    trigger: SpecTrigger;
+    axis: string;
+    from: string;
+    to: string;
+    variants?: string[] | undefined;
+    transition: SpecTransition | null;
+}
+/** Motion the code has that a Figma prototype cannot play (a looping spinner, keyboard focus, a popup opening). */
+export interface SpecMotionNote {
+    /** What moves, in plain words ("Looping animation spin, 700 ms"). */
+    what: string;
+    /** Why Figma does not play it. */
+    reason: string;
+    /** A keyframe animation: the token behind its duration ("motion.duration.spin"), when it is one. */
+    durationToken?: string | undefined;
+    /** Opening and closing: the code's transition when it opens (enter) and when it closes (exit), when it has one. */
+    enter?: SpecTransition | undefined;
+    exit?: SpecTransition | undefined;
+}
 /** A declaration, prop or part that has no Figma equivalent in this version, with the reason. */
 export interface SpecUnmapped {
     part: string;
@@ -209,6 +262,10 @@ export interface ComponentSpec {
     parts: SpecPart[];
     variants: SpecVariant[];
     unmapped: SpecUnmapped[];
+    /** Prototype interactions between the variants (hover, press, click to check), with the code's motion. */
+    interactions?: SpecInteraction[] | undefined;
+    /** Motion of the code a Figma prototype cannot play. */
+    motion?: SpecMotionNote[] | undefined;
 }
 /** An element of a code example: component export name, literal props, children (texts or elements). */
 export interface SpecExample {
@@ -275,7 +332,64 @@ export declare function hashSpec(spec: Omit<ComponentSpec, 'hash'> | ComponentSp
 export declare const variantName: (props: Record<string, string>) => string;
 /** Variant key independent of axis order (same as the plugin's signature keys): sorted "Size=md, Variant=primary". */
 export declare const variantKeyOf: (props: Record<string, string>) => string;
+/** What a set's description says about reduced motion: tokens set every duration to 0 under prefers-reduced-motion. */
+export declare const REDUCED_MOTION_NOTE = "In code, reduced motion turns this off.";
+/** One prototype reaction: on `trigger`, the variant `fromKey` changes to `toKey`, with the code's transition. */
+export interface MotionReaction {
+    trigger: SpecTrigger;
+    /** Figma's name for the trigger ("While hovering"). */
+    label: string;
+    from: Record<string, string>;
+    to: Record<string, string>;
+    /** variantKeyOf(from) and variantKeyOf(to). */
+    fromKey: string;
+    toKey: string;
+    transition: SpecTransition | null;
+}
+/** A component set's motion and interactions, read from its spec: for Figma prototypes, docs and reviews. */
+export interface ComponentMotion {
+    name: string;
+    /** Every reaction between variants, one per variant it starts from. */
+    reactions: MotionReaction[];
+    /** The interactions as the spec lists them (one per trigger and change), with the number of variants each covers. */
+    triggers: (SpecInteraction & {
+        label: string;
+        count: number;
+    })[];
+    /** Motion tokens the transitions use ("motion.duration.instant", "motion.easing.standard"), sorted. */
+    tokens: string[];
+    /** CSS properties that animate ("background-color"), sorted. */
+    properties: string[];
+    /** Where Figma plays the motion differently from the code. */
+    approximations: string[];
+    /** Motion of the code a Figma prototype cannot play. */
+    cannotPlay: SpecMotionNote[];
+    /** Opening and closing (a popup, a panel): the code's enter and exit transitions, when it has them. */
+    opening: {
+        enter: SpecTransition | null;
+        exit: SpecTransition | null;
+    } | undefined;
+    /** REDUCED_MOTION_NOTE when the component animates in code, else undefined. */
+    reducedMotion: string | undefined;
+}
+/**
+ * The motion of a component set from its spec: every reaction between its variants (trigger, from and to variants, the
+ * transition with duration and easing resolved from the motion tokens), the tokens and properties involved, what Figma
+ * approximates or cannot play, and the reduced motion note. Pure: works in the plugin, the browser and Node.
+ */
+export declare function componentMotion(spec: Pick<ComponentSpec, 'name' | 'variants' | 'interactions' | 'motion'>): ComponentMotion;
+/**
+ * Sets whose interactions use a motion token, directly or through an alias: `chainOf(path)` gives the tokens a path
+ * resolves through (resolve(...).chain), so a change to a primitive ("duration.75") finds the sets using
+ * "motion.duration.instant". Without it, only direct uses count. Sorted set names.
+ */
+export declare function componentsUsingMotionToken(specs: Pick<ComponentSpecsFile, 'components'>, tokenPath: string, chainOf?: (path: string) => string[]): string[];
 /** Parses component-specs.json; throws with a readable message when it is not a specs file of a known version. */
 export declare function parseComponentSpecs(text: string): ComponentSpecsFile;
 /** CSS custom property of a token path, with the repo convention (`cssVar` in bridge.config.json): "--" + path joined by "-". */
 export declare const tokenCssVar: (path: string, prefix?: string, separator?: string) => string;
+/** How a component stands in Figma, in Studio's words (the "In Figma" column): a short word and, for the ones not in Figma, the reason as a tooltip. Undefined: no data. */
+export declare function figmaCell(entry: SpecCoverage | undefined): {
+    label: string;
+    title?: string;
+} | undefined;

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import type { IntegrationsConfig } from './requests';
 import { type PreviewApps, type PreviewsConfig } from './previews';
 import { type Rights, type VisualImpactConfig } from './rights';
+import { type ProductConfig } from './products';
 /** File name Bridge looks for at the repository root. */
 export declare const CONFIG_FILE = "bridge.config.json";
 export interface RepoRef {
@@ -151,6 +152,8 @@ export interface BridgeConfig {
     integrations?: IntegrationsConfig | undefined;
     /** Visual before and after on pull requests: automatic (default) or on demand (label `visual-check`). */
     visualImpact?: VisualImpactConfig | undefined;
+    /** Apps that consume the design system, the default one being the library (see products.ts). Default DEFAULT_PRODUCTS. */
+    products: ProductConfig[];
 }
 type Partialish<T> = {
     [K in keyof T]?: T[K] | undefined;
@@ -210,6 +213,7 @@ export interface BridgeConfigInput {
     };
     integrations?: IntegrationsConfig;
     visualImpact?: Partial<VisualImpactConfig>;
+    products?: ProductConfig[];
 }
 export declare const DEFAULT_TOKEN_PATHS: TokenPaths;
 export declare const DEFAULT_GOVERNANCE: GovernanceConfig;

package/dist/docs-proposal.d.ts

@@ -0,0 +1,82 @@
+import { type ComponentDocsJson } from './docs-draft';
+import type { GitHubClient } from './github-client';
+import { type RiskResult } from './risk';
+/** One component's docs.json, before (null: a new file) and after, at its repo path. */
+export interface DocsFileEdit {
+    path: string;
+    component: string;
+    slug: string;
+    before: string | null;
+    after: string;
+}
+/** Who wrote the docs, for the pull request body and its source label. */
+export interface DocsOrigin {
+    /** "in the Bridge docs editor". */
+    where: string;
+    footer: string;
+    label: string;
+}
+export declare const DOCS_EDITOR_ORIGIN: DocsOrigin;
+export declare const DOCS_MCP_ORIGIN: DocsOrigin;
+export interface DocsIssue {
+    field: string;
+    message: string;
+}
+/** What blocks proposing a docs.json: a summary, no empty list items, no em dash (Bridge voice). */
+export declare function validateDocs(d: ComponentDocsJson): DocsIssue[];
+/** Drops empty list items and trims text, the way the editor saves. */
+export declare function cleanDocs(d: ComponentDocsJson): ComponentDocsJson;
+/** docs.json in the editor's canonical form: cleaned, in the Button.docs.json key order. Used to compare. */
+export declare const docsText: (d: ComponentDocsJson) => string;
+/** docs.json text the editor writes: cleaned, as a minimal diff of the file on main (or the branch) when there is one. */
+export declare const docsFileText: (d: ComponentDocsJson, original: string | null) => string;
+export interface DocsProposal {
+    branch: string;
+    title: string;
+    body: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    risk: RiskResult;
+    bump: 'patch';
+    labels: string[];
+}
+/** One pull request for the docs edits of a draft: branch, title, body, files with a patch changeset, the tier. */
+export declare function docsProposal(edits: DocsFileEdit[], opts: {
+    title?: string | undefined;
+    notes?: string | undefined;
+    date: Date;
+    packageName?: string | undefined;
+    changesetDir?: string | undefined;
+    origin?: DocsOrigin | undefined;
+}): DocsProposal;
+/**
+ * Opens one pull request with the docs edits from the default branch, the Jira key first in the title and the branch
+ * name (Jira's GitHub integration links them). Returns its number, link and branch. Labels are best effort.
+ */
+export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: {
+    base: string;
+    title?: string | undefined;
+    notes?: string | undefined;
+    jira?: string | null | undefined;
+    date?: Date | undefined;
+    origin?: DocsOrigin | undefined;
+    extraLabels?: string[] | undefined;
+    commitNote?: string | undefined;
+}): Promise<{
+    number: number;
+    url: string;
+    branch: string;
+    title: string;
+}>;
+/**
+ * Rewrites one file on an open branch in one commit (`next` gets the current text). Returns the commit sha, or ''
+ * when nothing changed. The Library editor saves an edited docs.json and accepts a Claude draft this way.
+ */
+export declare function commitFileOnGitHub(gh: GitHubClient, input: {
+    path: string;
+    branch: string;
+    message: string;
+    next: (text: string) => string;
+}): Promise<string>;

package/dist/github-client.d.ts

@@ -437,6 +437,7 @@ export declare class GitHubClient {
     getPullRequest(n: number): Promise<PullRequest & PullRequestSummary & {
         body: string;
         mergeable: boolean | null;
+        requestedReviewers: string[];
     }>;
     listPullRequestFiles(n: number): Promise<PullRequestFile[]>;
     updatePullRequest(n: number, patch: {
@@ -478,6 +479,94 @@ export declare class GitHubClient {
         };
     }): Promise<CheckRun>;
     removeLabel(issueNumber: number, label: string): Promise<void>;
+    /** The account the token belongs to (GET /user). Needs a token. */
+    getViewer(): Promise<{
+        login: string;
+    }>;
+    /** The repository's merge settings and the viewer's permissions (unknown settings count as allowed). */
+    getMergeSettings(): Promise<{
+        allow_squash_merge?: boolean;
+        allow_merge_commit?: boolean;
+        allow_rebase_merge?: boolean;
+        permissions?: {
+            admin?: boolean;
+            maintain?: boolean;
+            push?: boolean;
+        };
+    }>;
+    /**
+     * Merges a pull request, only at `sha` (GitHub refuses when the branch moved meanwhile). The repository's branch
+     * rules still apply: GitHub refuses a merge they block, whatever Bridge says.
+     */
+    mergePullRequest(n: number, input: {
+        method: 'squash' | 'merge' | 'rebase';
+        sha: string;
+        commitMessage?: string | undefined;
+    }): Promise<{
+        sha: string;
+        merged: boolean;
+    }>;
+    /** GitHub's "Update branch": merges the base into the pull request, only when its head is still `expectedHeadSha`. */
+    updatePullRequestBranch(n: number, expectedHeadSha: string): Promise<void>;
+    /** Posts a comment on an issue or pull request and returns its id and link. */
+    createIssueComment(n: number, body: string): Promise<{
+        id: number;
+        url: string;
+    }>;
+    /** Replaces the text of a comment. */
+    updateIssueComment(id: number, body: string): Promise<void>;
+    /** Submits a review on a given commit (the head the reviewer saw); the body may be empty for an approval. */
+    submitReview(n: number, input: {
+        event: 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
+        body?: string | undefined;
+        commitId?: string | undefined;
+    }): Promise<Review>;
+    /** Line comments of a pull request (review threads), oldest first. */
+    listReviewComments(n: number): Promise<{
+        id: number;
+        body: string;
+        author: string;
+        path: string;
+        line: number | null;
+        inReplyTo: number | null;
+        url: string;
+        createdAt: string;
+    }[]>;
+    /** Asks these people to review a pull request. */
+    requestReviewers(n: number, logins: string[]): Promise<void>;
+    /** Takes these people off the requested reviewers. */
+    removeRequestedReviewers(n: number, logins: string[]): Promise<void>;
+    /** Replies in the thread of a line comment. */
+    replyToReviewComment(n: number, commentId: number, body: string): Promise<{
+        id: number;
+        url: string;
+    }>;
+    /**
+     * What `head` adds on top of `base`, with what library sync needs: the shared start (merge base), the base
+     * commit and its tree, how far behind, and the files with their previous names.
+     */
+    compareDetailed(base: string, head: string): Promise<{
+        behindBy: number;
+        aheadBy: number;
+        mergeBase: string | null;
+        baseSha: string | null;
+        baseTree: string | null;
+        files: {
+            filename: string;
+            status: string;
+            previous_filename?: string | undefined;
+        }[];
+    }>;
+    /** A tree on top of `baseTree` from entries with their own file mode (blob sha, inline content, or sha null to delete). */
+    createTreeEntries(baseTree: string, entries: ({
+        path: string;
+        mode: string;
+        sha: string | null;
+    } | {
+        path: string;
+        mode: string;
+        content: string;
+    })[]): Promise<string>;
 }
 export declare function friendlyMessage(status: number, detail: string, info?: GitHubErrorInfo): string;
 export interface RepoFiles {

package/dist/index.d.ts

@@ -45,3 +45,12 @@ export * from './requests-github';
 export * from './component-spec';
 export * from './fidelity';
 export * from './fidelity-references';
+export * from './review-gate';
+export * from './library-update';
+export * from './branch-actions';
+export * from './jira';
+export * from './docs-proposal';
+export * from './share-branch';
+export * from './try-in-product';
+export * from './combine-branches';
+export * from './products';