@bridge-ds/core 0.5.1 → 0.7.0

package/dist/jira.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The Jira key given when a branch is created, normalised ("ds-42 " is "DS-42"), or null when empty. Throws a
+ * sentence that says how to fix it when the text is not a key.
+ */
+export declare function parseJiraKey(input: string | null | undefined): string | null;
+/** Whether a text is a Jira key, without throwing (for live field validation). */
+export declare const isJiraKey: (input: string) => boolean;
+/** The Jira key a title starts with ("DS-42 tokens: darker primary" gives "DS-42"), else null. */
+export declare function jiraKeyOf(title: string): string | null;
+/** The title without its leading Jira key. */
+export declare const withoutJiraKey: (title: string) => string;
+/** The pull request title with the key first: "DS-42 tokens: darker primary". Idempotent; no key, no change. */
+export declare function titleWithJiraKey(title: string, key: string | null): string;
+/** The branch name with the key first in its last part: "tokens/DS-42-darker-primary-20261019-1200". */
+export declare function branchWithJiraKey(branch: string, key: string | null): string;

package/dist/library-update.d.ts

@@ -0,0 +1,145 @@
+import type { GitHubClient, TreeEntry } from './github-client';
+import { type LayoutOptions, type TokenSet } from './token-set';
+import { type ContrastPair } from './wcag';
+import { type MergeChoices, type TokenMergeConflict, type TokenMergeInput, type TokenMergePlan } from './token-merge';
+/** A file of a compare (GET /repos/{o}/{r}/compare/{base}...{head}). */
+export interface CompareFile {
+    filename: string;
+    status: string;
+    previous_filename?: string | undefined;
+    sha?: string | null | undefined;
+}
+/** Files both the branch and main changed since they parted, split into token files and the rest (code). */
+export declare function overlap(changeFiles: CompareFile[], libraryFiles: CompareFile[], isTokenFile: (path: string) => boolean): {
+    tokenFiles: string[];
+    codeFiles: string[];
+};
+/** GitHub lists at most 300 files per compare: past that, Bridge cannot know what both sides touched. */
+export declare const COMPARE_FILE_LIMIT = 300;
+export type ConflictRoute = {
+    kind: 'tokens';
+    files: string[];
+} | {
+    kind: 'code';
+    alsoTokens: boolean;
+    files: string[];
+};
+/**
+ * Who resolves the conflict. Only token files on both sides: the designer, in Bridge. Any code file on both sides, a
+ * file list GitHub cut short, or no shared file at all (GitHub saw a conflict Bridge cannot explain): a developer.
+ */
+export declare function conflictRoute(o: {
+    tokenFiles: string[];
+    codeFiles: string[];
+}, opts?: {
+    truncated?: boolean;
+}): ConflictRoute;
+/** A rule from GET /repos/{o}/{r}/rules/branches/{branch}. */
+export interface BranchRuleLike {
+    type: string;
+    parameters?: {
+        dismiss_stale_reviews_on_push?: boolean;
+    } | null;
+}
+/**
+ * Whether GitHub dismisses approvals when new commits arrive, from the rules that apply to the library branch. True
+ * or false when a pull request rule says so; null when no rule says (classic branch protection is not readable
+ * without admin rights).
+ */
+export declare function dismissStaleFrom(rules: BranchRuleLike[] | null | undefined): boolean | null;
+/** The commit message of the resolution, so History and the branch say what the person chose. */
+export declare function resolutionMessage(input: {
+    library: string;
+    conflicts: TokenMergeConflict[];
+    choices: MergeChoices;
+    who?: string | null | undefined;
+}): string;
+export type LibraryState = 'current' | 'behind' | 'conflict' | 'unknown';
+export interface Freshness {
+    state: LibraryState;
+    /** Library updates (commits on the library branch) since the change started; null when not read. */
+    behindBy: number | null;
+    /** The commit the change and the library share. */
+    mergeBase: string | null;
+}
+/**
+ * How the change stands against the latest library. A conflict (mergeable false) wins: GitHub cannot combine them.
+ * Otherwise it is behind when the library has commits the change has not. A shipped or closed change has nothing to
+ * bring in. A compare that could not be read says unknown, never "up to date".
+ */
+export declare function freshness<C extends {
+    behind_by?: number | undefined;
+    merge_base_commit?: {
+        sha: string;
+    } | null | undefined;
+}>(input: {
+    compare: C | null | undefined;
+    mergeable: boolean | null | undefined;
+    open: boolean;
+}): Freshness;
+/** The compare of main and a branch head, in the shape the conflict reader needs (client.compareDetailed). */
+export interface LibraryCompare {
+    mergeBase: string | null;
+    baseSha: string | null;
+    baseTree: string | null;
+    files: CompareFile[];
+}
+export interface LibraryConflicts {
+    route: ConflictRoute;
+    /** Present for a pure token-file conflict. */
+    tokens?: {
+        root: string;
+        plan: TokenMergePlan;
+        input: TokenMergeInput;
+        sets: {
+            base: TokenSet;
+            mine: TokenSet;
+            theirs: TokenSet;
+        };
+        /** Every token file of each side, relative to the tokens root. */
+        mineFiles: Record<string, string>;
+        theirsFiles: Record<string, string>;
+        pairs: ContrastPair[];
+        options: LayoutOptions;
+    };
+    /** What the commit needs: main's tip and its tree, the branch head tree and its own files. */
+    write?: {
+        mainSha: string;
+        mainTree: string;
+        headSha: string;
+        headTree: Map<string, TreeEntry>;
+        changeFiles: CompareFile[];
+    };
+}
+/**
+ * What conflicts and who resolves it. Reads the files main changed since the branch started (one compare), then, for
+ * a pure token-file conflict, the token files at the shared start, in the branch and in main. `tokensRoot` is the
+ * best guess before the config is read (Studio: its site config); `contrastFallback` the contrast checks to use when
+ * main has none.
+ */
+export declare function readLibraryConflicts(gh: GitHubClient, compare: LibraryCompare, headSha: string, opts?: {
+    tokensRoot?: string | undefined;
+    contrastFallback?: string | undefined;
+}): Promise<LibraryConflicts>;
+/**
+ * Every token file once resolved, relative to the tokens root: main's files, the branch's own token files where only
+ * the branch touched them, and the merged files where both did.
+ */
+export declare function resolvedTokenFiles(data: LibraryConflicts, choices: MergeChoices): {
+    all: Record<string, string>;
+    merged: Record<string, string | null>;
+};
+/**
+ * Commits the resolution to the branch: a merge commit of main and the branch, whose tree is main plus the branch's
+ * own files plus the merged token files. Fast-forward only: when the branch moved meanwhile, GitHub refuses and
+ * nothing is lost.
+ */
+export declare function commitLibraryResolution(gh: GitHubClient, pull: {
+    head: {
+        ref: string;
+        sha: string;
+    };
+    base: {
+        ref: string;
+    };
+}, data: LibraryConflicts, choices: MergeChoices, who: string | null | undefined): Promise<string>;

package/dist/node/component-specs.d.ts

@@ -3,6 +3,8 @@ import { buildTokenSet } from '../token-set';
 export interface TokenInfo {
     path: string;
     type: string;
+    /** Durations and easings: the value in the default modes (`{ value: 150, unit: 'ms' }`, `[0.2, 0, 0, 1]`), for motion. */
+    value?: unknown;
 }
 export interface SpecGeneratorOptions {
     /** Repo-relative components directory ("packages/react/src/components"). */
@@ -14,11 +16,39 @@ export interface SpecGeneratorOptions {
     styleSuffix?: string | undefined;
     /** Repo-relative ESM build of lucide-react ("node_modules/lucide-react/dist/esm"), for the icons section. */
     lucideDir?: string | undefined;
+    /** Every component folder, to find components a file exports besides its own (Radio in RadioGroup.tsx). */
+    components?: string[] | undefined;
+    /** Repo-relative global stylesheet apps load before the components (inherited text styles, tag rules). */
+    baseCss?: string | undefined;
+    /** Repo-relative folder of specs drafted with Claude; default `component-spec-overrides` next to the specs file. */
+    overridesDir?: string | undefined;
 }
 /** "iconStart" -> "Icon start". */
 export declare const sentenceCase: (prop: string) => string;
+/**
+ * JSX text as React renders it (Babel's rule): lines trimmed where they meet a line break, empty lines dropped, the
+ * others joined with one space; spaces inside a line, and at the ends of a single line, are kept.
+ */
+export declare function jsxText(text: string): string;
+/** Renders the main component for one set of axis values, with stable part ids. */
+/**
+ * Which part of a component with a popup a set draws: the component without its popup (a select's trigger), or the
+ * popup alone drawn open (`*.Popup` under the `*.Portal`), the way a Figma UI kit draws menus and dialogs.
+ */
+export type SpecView = 'without-popup' | 'popup';
+/**
+ * Why a component cannot be drawn faithfully: thrown by the generator, recorded in the coverage list as the reason
+ * ("opens a popup", "uses CSS grid"). The message is plain language for designers.
+ */
+export declare class UnsupportedComponentError extends Error {
+    component: string;
+    reason: string;
+    constructor(component: string, reason: string);
+}
 /** The spec of one component, or an error message when it cannot be derived. */
-export declare function generateComponentSpec(name: string, opts: SpecGeneratorOptions): ComponentSpec;
+export declare function generateComponentSpec(name: string, opts: SpecGeneratorOptions, view?: SpecView, setName?: string, fixed?: Record<string, string>): ComponentSpec;
+/** Whether a spec draws anything: a fill, a border, an icon or a text of its own. Layout helpers draw nothing. */
+export declare function specDrawsSomething(spec: ComponentSpec): boolean;
 /** Icons every pulled file gets besides the ones the components use, so designers can swap without importing. */
 export declare const COMMON_ICONS: string[];
 /** The icon components themselves: Icon.tsx draws `sm` by default; Lucide's grid is 24, the `lg` size. */
@@ -32,16 +62,41 @@ export declare const MEDIA_SLOT: SpecSlot;
 export declare function generateIcons(components: ComponentSpec[], opts: SpecGeneratorOptions, slots?: SpecSlot[]): SpecIcon[];
 /** Content components the specs' slots swap to: each component's text slot (its default variant's text fields), then Media. */
 export declare function generateSlots(components: ComponentSpec[]): SpecSlot[];
+/** Specs of the named components (sets), in that order. Throws when one cannot be generated. */
 export declare function generateComponentSpecs(names: string[], opts: SpecGeneratorOptions): ComponentSpecsFile;
-/** The 6 base components of the first version. The generator works on any component folder. */
-export declare const SPEC_COMPONENTS: string[];
+/**
+ * Every component folder, generated when the generator can draw it faithfully, else recorded with the reason it
+ * cannot (unsupported) or as a layout helper with no visual of its own. Support is decided here, from what the generator
+ * can read: no list to maintain. A folder's other exports (Radio in RadioGroup) get their own set when they draw
+ * something; exports drawn inside the main set (CardHeader) do not.
+ */
+export declare function generateAllComponentSpecs(folders: string[], opts: SpecGeneratorOptions): ComponentSpecsFile;
+/** Where drafted specs live: next to component-specs.json (packages/react/component-spec-overrides). */
+export declare const overridesDirOf: (componentsDir: string) => string;
+/** FNV-1a of the code a drafted spec was read from, to tell when the code changed since. */
+export declare function draftedCodeHash(files: string[], read: (path: string) => string | undefined): string;
+/**
+ * A spec Claude drafted for a component the generator cannot read: `component-spec-overrides/<Folder>.json`, a
+ * ComponentSpec marked `"source": "drafted"` with the files it was read from (`files`), the generator's reason and the
+ * code's hash when drafted (`codeHash`). Validated like a generated spec, against the repo's tokens: an invalid one
+ * fails `npm run specs`. Never counted as generated: its coverage is `drafted`, and it is `stale` once the code changed.
+ */
+export declare function draftedSpec(folder: string, opts: SpecGeneratorOptions): ComponentSpec | undefined;
 /** CSS custom property -> token, for every token of the repo (all tiers), with the repo's cssVar convention. */
 export declare function tokenCssIndex(files: Record<string, string>, opts?: {
     prefix?: string;
     separator?: string;
     layout?: Parameters<typeof buildTokenSet>[1];
 }): Map<string, TokenInfo>;
-/** Specs of `names` for the repo at `root`, with bridge.config.json (tokens root, components dir, cssVar). */
+/** Generator options for the repo at `root` from bridge.config.json (tokens root, components dir, cssVar), and its component folders. */
+export declare function repoSpecOptions(root: string): {
+    opts: SpecGeneratorOptions;
+    folders: string[];
+};
+/**
+ * Specs for the repo at `root`. With `names`, those sets only (throws when one cannot be generated). Without, every
+ * component folder: the sets the generator can draw, and the coverage of all of them (what `npm run specs` writes).
+ */
 export declare function generateRepoComponentSpecs(root: string, names?: string[]): ComponentSpecsFile;
 /** The JSON text written to disk: stable, two-space indent, trailing newline. */
 export declare const serializeComponentSpecs: (f: ComponentSpecsFile) => string;

package/dist/node/index.d.ts

@@ -3,3 +3,4 @@ export * from './git-history';
 export * from './audit';
 export * from './component-specs';
 export * from './spec-css';
+export * from './spec-motion';