@bridge-ds/core 0.6.0 → 0.8.0

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

@@ -0,0 +1,66 @@
+import type { SpecEasing, SpecMotionNote, SpecTransition } from '../component-spec';
+import { type CssRule } from './spec-css';
+/** A CSS custom property's token, with its value resolved in the default modes (durations and easings). */
+export interface MotionToken {
+    path: string;
+    type: string;
+    value?: unknown;
+}
+/** One entry of a `transition` list: the property, and its duration, easing and delay as written. */
+export interface TransitionEntry {
+    property: string;
+    duration: string;
+    easing: string;
+    delay: string;
+}
+/** `var(--x)` replaced by the value of a non-token custom property the element has, recursively. */
+export declare function substituteVars(raw: string, computed: Map<string, string>, tokens: Map<string, MotionToken>, depth?: number): string;
+/**
+ * The transitions an element declares: the `transition` shorthand and the longhands (transition-property, -duration,
+ * -timing-function, -delay; shorter lists repeat, as in CSS). Local custom properties are substituted first.
+ */
+export declare function parseTransitions(computed: Map<string, string>, tokens: Map<string, MotionToken>): TransitionEntry[];
+/** A duration as milliseconds, with its token: "var(--motion-duration-fast)" -> 150 (motion.duration.fast). */
+export declare function resolveDuration(raw: string, tokens: Map<string, MotionToken>): {
+    ms: number;
+    token?: string;
+} | undefined;
+/**
+ * An easing Figma can play, with its token: a cubic bezier (token or `cubic-bezier()`, or a CSS keyword) is played
+ * exactly as Figma's custom bezier; linear as linear. steps() has no Figma easing: linear, recorded as approximated.
+ */
+export declare function resolveEasing(raw: string, tokens: Map<string, MotionToken>): {
+    easing: SpecEasing;
+    token?: string;
+    approximated?: string;
+} | undefined;
+/** The property a longhand belongs to, without its side: border-top-color -> border-color, padding-left -> padding. */
+export declare const shorthandOf: (prop: string) => string;
+/** The transition entry that animates `prop`: same name, `all`, or a shorthand of it (border-color for border-top-color). */
+export declare function entryFor(prop: string, entries: TransitionEntry[]): TransitionEntry | undefined;
+/** CSS properties whose value differs between two computed styles of a part (custom properties substituted). */
+export declare function changedProperties(from: Map<string, string> | undefined, to: Map<string, string> | undefined, tokens: Map<string, MotionToken>): string[];
+/**
+ * The transition Figma plays when a component goes from one variant to another: for every part, the CSS properties that
+ * change, animated by the destination state's `transition` (as in CSS). One duration and easing per reaction in
+ * Figma: the longest animated change, recorded as approximated when parts animate at other speeds or with a delay.
+ * Null when nothing that changes is animated in code (an instant change).
+ */
+export declare function transitionBetween(from: Map<string, Map<string, string>>, to: Map<string, Map<string, string>>, tokens: Map<string, MotionToken>): SpecTransition | null;
+/**
+ * Motion a Figma prototype cannot play, for the parts a set draws (`classes`: their "<module>|<class>" names):
+ * keyframe animations (a spinner, a shimmer), the keyboard focus ring, and opening or closing (a popup's enter motion,
+ * an accordion panel). `view` is the set's view: a popup drawn open, or a trigger without its popup.
+ */
+export declare function motionNotes(rules: CssRule[], classes: Set<string>, tokens: Map<string, MotionToken>, view?: 'popup' | 'without-popup', elements?: string[][]): SpecMotionNote[];
+/**
+ * The code's transitions when a part opens and when it closes, for the elements with open-state rules (`elements`, each
+ * the "<module>|<class>" names one element carries): the
+ * destination state's `transition` animates, as in CSS. Opening ends in the base rules plus the open rules
+ * ([data-open], [data-panel-open]...); closing ends in the base rules plus [data-ending-style] / [data-closed]. The
+ * properties are the ones those rules change. One transition per direction: the longest, as for interactions.
+ */
+export declare function openingTransitions(rules: CssRule[], elements: string[][], tokens: Map<string, MotionToken>): {
+    enter: SpecTransition | null;
+    exit: SpecTransition | null;
+};

package/dist/products.d.ts

@@ -0,0 +1,65 @@
+export interface ProductConfig {
+    /** Stable id: lowercase letters, digits and dashes ("admin"). The `product: <key>` label names it. */
+    key: string;
+    /** What people read ("Admin demo"). */
+    name: string;
+    /** "owner/name" when the product lives in another GitHub repository. */
+    repo?: string;
+    /** Folder of this repository, repo-relative ("apps/admin"). */
+    path?: string;
+    /** Preview URL pattern, same placeholders as previews.apps: {branch} {rawBranch} {pr} {sha} {sha7}. */
+    preview?: string;
+    /** react, vue, angular, svelte, astro, other. */
+    framework?: string;
+    /** The product a branch belongs to when nothing else matches: the library. */
+    default?: boolean;
+}
+/** What a config without `products` means: the Admin demo first, then the library (the default). */
+export declare const DEFAULT_PRODUCTS: ProductConfig[];
+/** Pull request labels that pin a branch to a product ("product: admin"). */
+export declare const PRODUCT_LABEL_PREFIX = "product: ";
+export declare const productLabel: (key: string) => string;
+/**
+ * Labels and a body line for new work started for a product (a branch, an exploration, a request): the
+ * `product: <key>` label and "**Product:** <name>". The default product adds nothing, since productOfBranch lands
+ * an unlabeled branch there. Studio, the CLI and the MCP server all write these.
+ */
+export declare function productMarks(products: readonly ProductConfig[], p: ProductConfig): {
+    labels: string[];
+    line: string;
+};
+/** The configured products, or DEFAULT_PRODUCTS when the config lists none. */
+export declare function productsOf(config: {
+    products?: ProductConfig[] | undefined;
+} | null | undefined): ProductConfig[];
+/** The product marked `default: true`, else the last one listed. */
+export declare function defaultProduct(products: readonly ProductConfig[]): ProductConfig;
+/** A product by key or name, whatever the case. */
+export declare function findProduct(products: readonly ProductConfig[], keyOrName: string | null | undefined): ProductConfig | undefined;
+/**
+ * The product a branch belongs to: a `product: <key>` label naming a known product wins; else the first product
+ * (other than the default) whose folder holds one of the changed files; else the default product. Files not read
+ * yet (null) land on the default, since every branch of the repository starts from the library.
+ */
+export declare function productOfBranch(products: readonly ProductConfig[], branch: {
+    files?: readonly string[] | null | undefined;
+    labels?: readonly (string | {
+        name: string;
+    })[] | null | undefined;
+}): ProductConfig;
+/**
+ * The product a place belongs to: a product whose `repo` is the current repository (when that is not the design
+ * system repository itself); else the product whose folder holds `relPath` (the deepest one); else the default.
+ */
+export declare function productForPlace(products: readonly ProductConfig[], place: {
+    relPath?: string | null | undefined;
+    repo?: string | null | undefined;
+    designSystemRepo?: string | null | undefined;
+}): {
+    product: ProductConfig;
+    how: 'repo' | 'path' | 'default';
+};
+/** What is wrong with a `products` value, each problem saying how to fix it. Empty: valid (or absent). */
+export declare function productProblems(raw: unknown): string[];
+/** Whether two product lists say the same thing (toConfigJson leaves the default list out). */
+export declare function sameProducts(a: readonly ProductConfig[], b: readonly ProductConfig[]): boolean;

package/dist/review-gate.d.ts

@@ -0,0 +1,251 @@
+import type { OverridePolicy } from './config';
+import { type ShipPolicy } from './rights';
+import { type RiskTier } from './risk';
+export interface LabelLike {
+    name: string;
+}
+/** Tier from labels (`tier-3`, `tier: 3`, `risk:3`), the PR template checkbox (`- [x] Tier 3`) or a `Risk tier: 3` line. Highest wins. */
+export declare function parseTier(labels: LabelLike[], body: string | null | undefined): RiskTier | null;
+/** What GitHub returns about a pull request's lifecycle. `merged_at` is set once merged; `state` is then "closed". */
+export interface PullStateLike {
+    state?: string;
+    draft?: boolean;
+    merged?: boolean;
+    merged_at?: string | null;
+}
+export type PullState = 'merged' | 'closed' | 'draft' | 'open';
+/** Merged wins over closed (GitHub reports merged pull requests as closed), closed over draft, draft over open. */
+export declare function pullState(p: PullStateLike): PullState;
+/** Label and pill tone of each state, for list and detail views. */
+export declare const PULL_STATE_PILL: Record<PullState, {
+    label: string;
+    cls: string;
+}>;
+/** Pull requests still waiting for review (open or draft): merged and closed ones never count as open reviews. */
+export declare function openPulls<P extends PullStateLike>(pulls: P[]): P[];
+export interface CiRunLike {
+    name: string;
+    status: 'queued' | 'in_progress' | 'completed' | string;
+    conclusion: string | null;
+    html_url?: string;
+}
+export interface CiStatusLike {
+    context: string;
+    state: 'success' | 'failure' | 'error' | 'pending' | string;
+    target_url?: string | null;
+}
+export type CiState = 'pass' | 'fail' | 'pending' | 'none';
+export interface CiSummary {
+    state: CiState;
+    total: number;
+    passed: number;
+    failed: {
+        name: string;
+        url?: string;
+    }[];
+    pending: {
+        name: string;
+        url?: string;
+    }[];
+}
+/** Combines check runs and commit statuses into one verdict. Any failure wins over pending. */
+export declare function summarizeCi(runs: CiRunLike[], statuses?: CiStatusLike[]): CiSummary;
+export interface ReviewLike {
+    user: {
+        login: string;
+    } | null;
+    state: 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING' | string;
+    submitted_at?: string | null;
+}
+export interface ApprovalSummary {
+    approvers: string[];
+    changesRequested: string[];
+    design: boolean;
+    tech: boolean;
+}
+/** Latest decisive review per person (comments do not reset an approval), then owner coverage. */
+export declare function summarizeApprovals(reviews: ReviewLike[], owners: {
+    design: string[];
+    tech: string[];
+}, author?: string): ApprovalSummary;
+export type MissingApproval = 'design approval' | 'tech approval' | 'approval';
+export interface MergeGate {
+    allowed: boolean;
+    reasons: string[];
+    /** True when the only failing reasons are missing approvals and the viewer is in `governance.override.allowed`. */
+    overridable: boolean;
+    /** Approvals still missing, in the words the override comment uses. */
+    missing: MissingApproval[];
+    /** Whether the viewer holds the right to ship (true when no rule singles anyone out or the viewer is unknown). */
+    canShip: boolean;
+}
+/** Whether `login` may use the owner override. Case-insensitive, a leading @ is ignored. */
+export declare function canOverride(login: string | null | undefined, policy: OverridePolicy | null | undefined): boolean;
+/**
+ * Whether the Merge button is enabled, and why not. Mirrors docs/GOVERNANCE.md.
+ * The owner override only ever covers missing approvals: CI failing or running, changes requested, a draft,
+ * a closed pull request or a merge conflict always block, for everyone.
+ */
+export declare function mergeGate(input: {
+    tier: RiskTier | null;
+    ci: CiSummary;
+    approvals: ApprovalSummary;
+    draft: boolean;
+    mergeable?: boolean | null;
+    state: string;
+    merged_at?: string | null;
+    /** Login of the connected viewer (GitHub /user). */
+    viewer?: string | null;
+    override?: OverridePolicy | null;
+    /** A running exploration (label `exploration`): never merged as is, whatever else is green. */
+    exploration?: boolean;
+    /** Who may ship (shipPolicy from governance.rights). null or absent: anyone with write access. */
+    ship?: ShipPolicy | null;
+}): MergeGate;
+/** The gate reason of a conflict, in the words a designer reads. Detected by identity, never by regex. */
+export declare const CONFLICT_REASON = "It conflicts with main: resolve it with Update from main on the branch.";
+export declare const OVERRIDE_HEADING = "**Bridge owner override**";
+/** Problem with an override reason, or null when it is accepted. */
+export declare function overrideReasonProblem(reason: string, policy: OverridePolicy): string | null;
+/**
+ * The audit comment posted on the pull request before an override merge. Stable format: History and the PR
+ * timeline find it by its first line, `**Bridge owner override**`, and read it back with parseOverrideComment.
+ */
+export declare function overrideComment(login: string, reason: string, missing: MissingApproval[]): string;
+/** The comment body after GitHub refused the merge, so the audit trail does not claim a merge that never happened. */
+export declare function overrideRefusedComment(body: string, message: string): string;
+export interface OverrideRecord {
+    login: string;
+    reason: string;
+    missing: string[];
+    merged: boolean;
+}
+/** Reads an override comment back; null for any other comment. */
+export declare function parseOverrideComment(body: string | null | undefined): OverrideRecord | null;
+export type MergeMethod = 'squash' | 'merge' | 'rebase';
+/** Merge methods the repo allows, squash first. Unknown settings (no push access) count as allowed. */
+export declare function allowedMergeMethods(repo: {
+    allow_squash_merge?: boolean;
+    allow_merge_commit?: boolean;
+    allow_rebase_merge?: boolean;
+} | null | undefined): MergeMethod[];
+/** Whether the viewer can write to the repo, from `permissions` on GET /repos/{owner}/{repo} with their token. */
+export declare function hasWriteAccess(perms: {
+    admin?: boolean;
+    maintain?: boolean;
+    push?: boolean;
+} | null | undefined): boolean;
+export type ReviewStatusKind = 'merged' | 'closed' | 'draft' | 'ci-failing' | 'changes-requested' | 'ci-running' | 'needs-design' | 'needs-tech' | 'needs-approval' | 'conflict' | 'checking' | 'ready' | 'unknown';
+/**
+ * Sort order for a "needs you" list, most urgent first: what blocks the merge, then what waits for an approval,
+ * then what is ready, then running checks and unknown ones, drafts and finished ones last. Lower comes first.
+ */
+export declare const REVIEW_STATUS_ORDER: Record<ReviewStatusKind, number>;
+/**
+ * One status chip for a pull request, from real data. Same rules and order as the pull request header
+ * (lib/changes needFromDetail): lifecycle, draft, CI failing, changes requested, merge conflict, CI running, then
+ * missing approvals (Tier 3 by default), then ready. `mergeable` null means GitHub has not computed it yet: the chip
+ * reads "Checking" instead of an approval or "Ready to ship", so a list never says something the detail contradicts.
+ * Undefined means it was not read: no conflict known. `ready` is returned only when mergeGate allows the merge.
+ * Unknown CI or reviews (null, still loading or failed) never read as ready.
+ */
+export declare function reviewStatusKind(input: {
+    state?: string;
+    draft?: boolean;
+    merged_at?: string | null;
+    ci: CiSummary | null;
+    approvals: ApprovalSummary | null;
+    tier: RiskTier | null;
+    mergeable?: boolean | null;
+}): ReviewStatusKind;
+export interface QueuePull extends PullStateLike {
+    state: string;
+    labels?: ({
+        name?: string;
+    } | string)[];
+    head: {
+        ref: string;
+    };
+    user?: {
+        login: string;
+        type?: string;
+    } | null;
+}
+/** The changesets release pull request ("Version packages"), on a changeset-release/* branch. */
+export declare const isReleasePull: (p: Pick<QueuePull, "head">) => boolean;
+/** Opened by GitHub automation, not by a person: the release pull request or anything github-actions[bot] opened. */
+export declare function isAutomationPull(p: Pick<QueuePull, 'head' | 'user'>): boolean;
+/** The open pull requests that wait for a review, in the order given. Every count in the Studio comes from here. */
+export declare function reviewQueue<P extends QueuePull>(pulls: P[]): P[];
+/** The open release pull request, if the changesets action opened one. */
+export declare function releasePull<P extends QueuePull>(pulls: P[]): P | null;
+/**
+ * The approval a change needs, the same rule everywhere: the tier the author set (label, PR template checkbox or
+ * "Risk tier" line) or the one the shared classifier computes from the changed files, highest wins. Without files
+ * (not read yet) only a label counts, and a missing label stays unknown.
+ */
+export declare function effectiveTier(labels: LabelLike[], body: string | null | undefined, files: {
+    filename: string;
+    status?: string;
+}[] | null): RiskTier | null;
+export type ReopenEligibility = 
+/** The branch is still there: the change can be reopened as it was. */
+{
+    kind: 'reopen';
+}
+/** The branch is gone: nothing to reopen, but its token edits can start a new change. */
+ | {
+    kind: 'gone';
+}
+/** Not closed, or not the viewer's to reopen, or not known yet. */
+ | {
+    kind: 'none';
+};
+/**
+ * Whether the viewer can reopen a closed change: only a change closed without shipping, only its author or an owner
+ * (governance.owners, both roles), and only someone GitHub lets write (write access, or the author). `branch` is what
+ * GitHub said about the head branch: there, removed, or not read.
+ */
+export declare function reopenEligibility(x: {
+    state: PullState;
+    viewer: string | null;
+    author: string;
+    owners: string[];
+    canWrite: boolean;
+    branch: 'exists' | 'gone' | 'unknown';
+}): ReopenEligibility;
+export type ApprovalRole = 'design' | 'tech' | 'approval';
+/** The approvals a tier needs, as mergeGate counts them (Tier 2 and 3: design and tech; Tier 1: one approval). */
+export declare function requiredApprovals(tier: RiskTier | null): ApprovalRole[];
+/** The approvals still missing on a branch, from its tier and the reviews read (empty when either is unknown). */
+export declare function pendingApprovals(tier: RiskTier | null | undefined, approvals: ApprovalSummary | null | undefined): ApprovalRole[];
+/**
+ * Who can still give an approval: the owners listed for the role (both lists for a plain approval) minus the author
+ * and anyone who already approved. `open`: the config lists nobody for the role, so any reviewer but the author counts.
+ */
+export declare function eligibleReviewers(role: ApprovalRole, p: {
+    owners: {
+        design: string[];
+        tech: string[];
+    };
+    author: string;
+    approvers?: string[] | undefined;
+}): {
+    open: boolean;
+    logins: string[];
+    listed: string[];
+};
+/**
+ * "Ask someone else to review": the other people who can give the missing approvals, never the viewer or the author.
+ * Empty when nobody else can (the caller says to review it or to add a reviewer in Settings).
+ */
+export declare function reviewersToAsk(x: {
+    tier: RiskTier | null;
+    approvals: ApprovalSummary;
+    owners: {
+        design: string[];
+        tech: string[];
+    };
+    author: string;
+    viewer: string | null | undefined;
+}): string[];

package/dist/share-branch.d.ts

@@ -0,0 +1,85 @@
+/** The dialog's explanation, in designer words. */
+export declare const SHARE_EXPLAIN = "Product teams can install this branch in their app before it is merged, and remove it any time.";
+export type ChangeLifecycle = 'open' | 'draft' | 'merged' | 'closed';
+type Source = 'pkg.pr.new' | 'release' | 'other';
+export type ShareState = 
+/** The command for the latest update is posted. */
+{
+    kind: 'ready';
+    command: string;
+    source: Source;
+}
+/** No command for the latest update yet. */
+ | {
+    kind: 'building';
+}
+/** The workflow posted for the latest update but could not publish. */
+ | {
+    kind: 'failed';
+}
+/** The change touches none of the preview packages: there is nothing to install. */
+ | {
+    kind: 'no-packages';
+}
+/** Shipped or closed. `stillWorks` from where the preview lived; null when no preview was ever posted. */
+ | {
+    kind: 'shipped' | 'closed';
+    stillWorks: boolean | null;
+    command: string | null;
+};
+/** `@bridge-ds/react` -> `packages/react/`, the folder the workflow builds it from (PACKAGE_DIRS). */
+export declare const packageDir: (name: string) => string;
+/** True when a changed file is inside one of the preview packages. */
+export declare function touchesPackages(files: readonly string[], packages: readonly string[]): boolean;
+/**
+ * Whether a change offers sharing at all: never from a fork (the workflow cannot publish from one) or when the
+ * repository has no preview packages configured.
+ */
+export declare const canShare: (x: {
+    fromFork: boolean;
+    packages: readonly string[];
+}) => boolean;
+/**
+ * Where the preview of a change stands, from its lifecycle, its changed files and the sticky preview comment. A
+ * comment about an older update than the head means the new one is still being prepared: its command is never shown.
+ */
+export declare function shareState(x: {
+    lifecycle: ChangeLifecycle;
+    files: readonly string[];
+    packages: readonly string[];
+    comment: string | null | undefined;
+    headSha: string;
+}): ShareState;
+/**
+ * Whether the change page shows the action: always while the change is open or a draft (the dialog says why there is
+ * nothing to install yet), and after it ships or closes only when a preview was posted that a team may have installed.
+ */
+export declare const showShare: (lifecycle: ChangeLifecycle, s: ShareState) => boolean;
+/** The dialog's description: the explanation while the change can still be tried, where it stands once finished. */
+export declare const shareDescription: (s: ShareState) => string;
+/** How a product goes back to the released packages. */
+export declare const stableCommand: (packages: readonly string[]) => string;
+/** The one sentence the dialog shows under its explanation, in designer words. Null when the message says it all. */
+export declare function stateSentence(s: ShareState): string | null;
+export interface ShareMessageInput {
+    title: string;
+    state: ShareState;
+    packages: readonly string[];
+    /** "Try it in the product": the admin preview with this change, when GitHub reports one. */
+    tryUrl?: string | null | undefined;
+    /** The change on GitHub, for the developer. */
+    url: string;
+}
+export interface ShareMessage {
+    subject: string;
+    body: string;
+}
+/**
+ * The ready-to-paste message for a developer of a product team: the change, the preview install command, where to
+ * see it first, how long the preview lasts and how to go back. Plain text, for a chat or an email. Null when there is
+ * nothing to install and nothing to undo (still building, failed, no packages, or never posted).
+ */
+export declare function shareMessage(x: ShareMessageInput): ShareMessage | null;
+/** "Open in email": a mailto link with the subject and body. Nothing is sent by Studio. */
+export declare const mailtoHref: (m: ShareMessage) => string;
+export {};

package/dist/try-in-product.d.ts

@@ -0,0 +1,16 @@
+import { type BranchPreviewSources, type PreviewApps } from './previews';
+export interface ProductScreen {
+    label: string;
+    route: string;
+    tenant: string;
+    theme: string;
+}
+/** The admin preview of a change, or null when GitHub reports none (or the build failed, or it comes from a fork). */
+export declare function productPreview(apps: PreviewApps, ctx: {
+    branch: string;
+    pr: number;
+    sha: string;
+    fromFork?: boolean;
+}, sources: BranchPreviewSources): string | null;
+/** The preview with the toolbar on, at that screen (shop and theme in the query, the hash route ra-core reads), else home. */
+export declare function tryInProductUrl(preview: string, pr: number, screen: ProductScreen | null): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Bridge core: bridge.config.json, DTCG token loading (tiers and layered modes), alias resolution, WCAG contrast, diffs, minimal-diff edits, PR body, the shared risk tier classifier, changesets and a fetch-based GitHub client. No Figma API, no DOM; Node-only helpers (git, reading a product folder) under @bridge-ds/core/node; the adoption audit under @bridge-ds/core/audit.",
   "license": "MIT",