@bridge-ds/core 0.20.0 → 0.21.0

package/dist/prod-branch-github.d.ts

@@ -86,6 +86,12 @@ export interface OpenLibraryBranchInput {
      * the token only needs Issues write. Callers pass changesMode(config), or an explicit choice.
      */
     mode?: ChangesMode | undefined;
+    /**
+     * The design system repository, when the product branch lives in the product's own repository (`gh` reads that
+     * one): the library side (request, suggestion, library exploration) is opened here, and the product branch keeps the
+     * link. Its preview cannot be merged across repositories, so `usePreview` does nothing then.
+     */
+    library?: GitHubClient | undefined;
 }
 /** What writeTokens returns: the pull request it opened, or the suggestion it filed. */
 export type LibraryTokenWrite = {
@@ -107,7 +113,7 @@ export interface OpenedLibraryBranch {
     warnings: string[];
 }
 /** The product branch as the library side names it. */
-export declare function productBranchRef(pull: Pick<Pull, 'number' | 'title' | 'headRef' | 'url' | 'author' | 'body'>, product: ProductConfig): ProductBranchRef;
+export declare function productBranchRef(pull: Pick<Pull, 'number' | 'title' | 'headRef' | 'url' | 'author' | 'body'>, product: ProductConfig, repo?: string): ProductBranchRef;
 /**
  * Opens the library side of a missing piece and links both ways: the library branch (or request) says "Needed by" the
  * product branch and carries the `needed-by-product` label; the product branch records the link. A token piece opens a
@@ -134,11 +140,17 @@ export interface ProductBranchView {
     /** Pieces with no library branch yet. */
     open: MissingPiece[];
 }
-/** Where one linked library branch stands, and what its preview means for the product branch. */
+/**
+ * Where one linked library branch stands, and what its preview means for the product branch. `gh` reads the library
+ * side. `opts.across`: the product branch lives in the product's own repository, so the library change reaches it as
+ * an npm release, never by a merge: nothing is compared across the two repositories.
+ */
 export declare function linkedLibraryBranchOnGitHub(gh: GitHubClient, link: LibraryLink, product: {
     headSha: string;
     baseRef: string;
-}, piece?: MissingPiece): Promise<LinkedLibraryBranch>;
+}, piece?: MissingPiece, opts?: {
+    across?: boolean;
+}): Promise<LinkedLibraryBranch>;
 /**
  * Everything a product branch page shows: the record, the sentence, and each linked library branch with its status,
  * its reviewers and what its preview means for the product branch. A few reads per linked branch.
@@ -146,7 +158,8 @@ export declare function linkedLibraryBranchOnGitHub(gh: GitHubClient, link: Libr
 export declare function productBranchViewOnGitHub(gh: GitHubClient, pr: number, opts: {
     products: readonly ProductConfig[];
     viewer?: string | null | undefined;
-    agentName?: string | undefined;
+    agentName?: string | undefined; /** The design system repository, when `gh` reads a product's own one: its requests and library branches are read there. */
+    library?: GitHubClient | undefined;
 }): Promise<ProductBranchView>;
 /**
  * "Switch to the published version": once the library branch shipped, main comes into the product branch (GitHub's
@@ -157,4 +170,41 @@ export declare function switchToPublishedOnGitHub(gh: GitHubClient, pr: number):
     status: 'switched' | 'up-to-date';
     said: string;
 }>;
+export interface ProposedPieces {
+    /** Requests filed now, one per ticked piece (number 0 in a dry run). */
+    proposed: {
+        piece: string;
+        title: string;
+        number: number;
+        url: string;
+    }[];
+    /** Ticked pieces that already have a library side: never sent twice. */
+    already: {
+        piece: string;
+        number: number;
+    }[];
+    /** Ticked ids the record does not know. */
+    unknown: string[];
+    warnings: string[];
+}
+/**
+ * "Done exploring", the library side: each piece the designer ticks becomes a request for the DS lead (the request
+ * mechanism of requests.ts, labeled `needed-by-product`, with the "Needed by" block and the exploration's preview
+ * link), and the exploration records the link so it is never sent twice. Unticked pieces are not proposed. A branch
+ * outside any product (a library exploration) is named after the library.
+ */
+export declare function proposePiecesOnGitHub(gh: GitHubClient, pr: number, input: {
+    pieces: readonly string[];
+    products: readonly ProductConfig[];
+    previewUrl?: string | null | undefined;
+    openedBy?: string | undefined;
+    agent?: string | undefined;
+    source?: RequestSource | undefined;
+    dryRun?: boolean | undefined;
+    /**
+     * The design system repository, when the exploration lives in a product's own repository (`gh` reads that one):
+     * the requests are filed there, where the DS lead works, and link back to the product pull request as owner/name#n.
+     */
+    library?: GitHubClient | undefined;
+}): Promise<ProposedPieces>;
 export {};

package/dist/prod-branch.d.ts

@@ -6,7 +6,7 @@ import type { TokenEdit } from './token-edits';
 /** What the library lacks: a token value, a variant of an existing component, or a component. */
 export type PieceKind = 'token' | 'variant' | 'component';
 /** What a variant changes on its component, in designer words. */
-export type PieceAspect = 'tone' | 'shape' | 'size' | 'style';
+export type PieceAspect = 'tone' | 'shape' | 'size' | 'style' | 'state';
 export interface PieceValue {
     /** Audit category: color, radius, spacing... */
     category: string;
@@ -14,7 +14,11 @@ export interface PieceValue {
     property?: string | undefined;
     /** As written: "#c2410c", "10px". */
     value: string;
+    /** The part of the component the value lands on, in plain words: "icon" for `.wishlist svg`. */
+    part?: string | undefined;
 }
+/** How a request names a value: "fill (icon)", "background-color", "color". */
+export declare const pieceValueField: (v: PieceValue) => string;
 export interface PieceNearest {
     /** Token path of the closest library value: color.feedback.danger.bg. */
     token: string;
@@ -46,6 +50,15 @@ export interface MissingPiece {
         file: string;
         line: number;
     }[];
+    /**
+     * Set when the branch restyles a library component from outside (its CSS or style, through a class or a state
+     * selector) using only tokens or keywords: no hand-picked value, but a look or a state the component lacks. Pieces
+     * built from hand-picked values leave it out.
+     */
+    restyle?: {
+        state?: string | undefined;
+        selector: string;
+    } | undefined;
     /** Token pieces: the token the library branch would add (one value, every file the closest token lives in). */
     token?: {
         path: string;
@@ -71,6 +84,11 @@ export interface LibraryLink {
     agent?: string | undefined;
     /** ISO date. */
     at: string;
+    /**
+     * "owner/name" of the design system repository, when the product branch lives in the product's own repository:
+     * "#12" alone would point at the product's own issue 12 there.
+     */
+    repo?: string | undefined;
 }
 /** What the product branch body keeps: the last check and the library branches opened for its pieces. */
 export interface PiecesRecord {
@@ -117,6 +135,13 @@ export interface NeededBy {
     /** The closest thing the library has today, so a reviewer can suggest it instead: "danger". */
     nearest?: string | undefined;
     nearestToken?: string | undefined;
+    /** Its value, as the audit resolved it: "#c3184c". */
+    nearestValue?: string | undefined;
+    /**
+     * "owner/name" when the product branch lives in the product's own repository: the request is filed in the design
+     * system repository, so "#12" alone would point at the wrong pull request there.
+     */
+    repo?: string | undefined;
 }
 /** "Needed by" for a library branch body: one line people read, one hidden block tools read. */
 export declare function neededBySection(n: NeededBy): string;
@@ -131,6 +156,8 @@ export interface ProductBranchRef {
     productKey: string;
     productName: string;
     author?: string | undefined;
+    /** "owner/name" when the product branch lives in the product's own repository (not the design system one). */
+    repo?: string | undefined;
 }
 export type LibraryBranchPlan = {
     kind: 'token-change';
@@ -163,6 +190,20 @@ export declare function libraryBranchPlan(piece: MissingPiece, branch: ProductBr
     requestedBy?: string | undefined;
     mode?: ChangesMode | undefined;
 }): LibraryBranchPlan;
+/**
+ * The request a piece becomes when a designer says "Done exploring" and ticks it: always a request (an issue), never a
+ * branch, so the DS lead decides on it first. A token is asked for beside the closest token, a variant on its
+ * component, a new component as one. The summary links the exploration's preview, so the DS lead sees the piece in
+ * context. The "Needed by" block (withNeededBy, the plan's `neededBy`) goes on the issue too.
+ */
+export declare function pieceRequest(piece: MissingPiece, branch: ProductBranchRef, opts?: {
+    previewUrl?: string | null | undefined;
+    source?: ComponentChangeRequest['source'];
+    requestedBy?: string | undefined;
+}): {
+    request: ComponentChangeRequest;
+    neededBy: NeededBy;
+};
 export type LinkStatusKey = 'draft' | 'in-review' | 'changes' | 'approved' | 'shipped' | 'closed' | 'exploring' | 'requested' | 'in-progress' | 'done' | 'declined' | 'outdated';
 export interface LinkStatus {
     key: LinkStatusKey;

package/dist/products.d.ts

@@ -59,6 +59,23 @@ export declare function productForPlace(products: readonly ProductConfig[], plac
     product: ProductConfig;
     how: 'repo' | 'path' | 'default';
 };
+/**
+ * The repository an exploration for this product is created in: the product's own repository when the team connected
+ * one (`repo`, other than the design system repository), so developers check the branch out in their own
+ * environment and get the library from npm. Null otherwise (a product folder of the design system repository, the
+ * library itself, the demo workspace): the exploration then lives in the design system repository.
+ */
+export declare function productRepoOf(p: ProductConfig | null | undefined, designSystemRepo: string | null | undefined): string | null;
+/**
+ * The products whose explorations live in their own repository (productRepoOf), each with that repository, one entry
+ * per repository (the first product listed wins when two share one). Lists read each of them once.
+ */
+export declare function productRepos(products: readonly ProductConfig[], designSystemRepo: string | null | undefined): {
+    product: ProductConfig;
+    repo: string;
+}[];
+/** The product whose own repository is `repo` ("owner/name", any case), or undefined (the design system repository). */
+export declare function productOfRepo(products: readonly ProductConfig[], repo: string | null | undefined, designSystemRepo?: string | null | undefined): ProductConfig | undefined;
 /** 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). */