@bridge-ds/core 0.19.0 → 0.20.0

package/dist/measure-location.d.ts

@@ -0,0 +1,42 @@
+/** The data branch the automatic measure publishes to: the requests branch the plugin already writes to. */
+export declare const MEASURE_BRANCH = "bridge-requests";
+/** The story shots folder `bridge specs --measure --shots` writes next to measured-specs.json. */
+export declare const MEASURED_SHOTS_DIR = "measured-shots";
+/** The workflow that keeps the measure fresh, in the team's repo. */
+export declare const MEASURE_WORKFLOW_FILE = ".github/workflows/bridge-measure.yml";
+/** The one action that turns the measure on, as Studio and the plugin name it. */
+export declare const MEASURE_SETUP_ACTION = "Set up automatic measure";
+/** What a designer reads when there is no measure yet: calm, and the next step. */
+export declare const MEASURE_MISSING_TEXT = "Bridge hasn't measured your components yet. A developer turns it on once: Set up automatic measure.";
+/** How a developer turns it on, in lines (the copied request, the MCP tools, the CLI). */
+export declare function measureSetupSteps(repo?: string): string[];
+/** Where a measure was found: the repo at the ref read, or the measure branch. */
+export interface FoundMeasure {
+    text: string;
+    /** Its path, the same in both places. */
+    path: string;
+    /** Undefined: the repo (at the ref the reader works on); else the branch it came from. */
+    branch?: string | undefined;
+}
+/** Reads one file: from the repo at the reader's ref, or from a named branch. Undefined when it is not there. */
+export interface MeasureFiles {
+    repo(path: string): Promise<string | null | undefined>;
+    /** Undefined when the reader cannot reach GitHub (local, no token): only the repo is read then. */
+    branch?: ((path: string, branch: string) => Promise<string | null | undefined>) | undefined;
+}
+/**
+ * The measure, where the readers agree it lives: `path` in the repo first (a measure committed on purpose), else on
+ * the measure branch (the automatic measure). Undefined when neither has it. A branch read that fails (no access, the
+ * network) counts as not there: the caller then says the measure is missing, calmly.
+ */
+export declare function findMeasure(files: MeasureFiles, path?: string): Promise<FoundMeasure | undefined>;
+/** "measured-specs.json" or "measured-specs.json on bridge-requests". */
+export declare const measureFromWords: (m: Pick<FoundMeasure, "path" | "branch">) => string;
+/** The folder a measure's shot paths are relative to: the folder of measured-specs.json ('' at the root). */
+export declare const measureDir: (path: string) => string;
+/** Thrown by readers when there is no measure: the message is the designer sentence, the steps follow for a developer. */
+export declare class MeasureMissingError extends Error {
+    readonly code = "measure-missing";
+    readonly steps: string[];
+    constructor(repo?: string, extra?: string[]);
+}

package/dist/measure-workflow.d.ts

@@ -0,0 +1,48 @@
+/** The published CLI the template runs: the first version with every measure flag the workflow passes. */
+export declare const MEASURE_CLI_PACKAGE = "@bridge-ds/cli@^0.13.0";
+/** What the measure reads in each story: every variant, in these states, the variables, a shot of each. */
+export declare const MEASURE_FLAGS = "--variants --states rest,hover,active,disabled --tokens --shots --check";
+/** Files whose change can change what the Storybook draws, when nothing more precise is known. */
+export declare const MEASURE_DEFAULT_PATHS: string[];
+export interface MeasureWorkflowOptions {
+    /** The default branch (bridge.config.json repo.defaultBranch). Default main. */
+    defaultBranch?: string | undefined;
+    /**
+     * The deployed Storybook (bridge.config.json previews.production.storybook). Set: the workflow measures it once a
+     * deploy of it succeeds. Empty: it builds Storybook in the run and measures that build (any Storybook, private ones too).
+     */
+    storybookUrl?: string | undefined;
+    /**
+     * Deployed Storybook only: a word of the deploy's status or environment name ("Vercel – bridge-storybook"), so the
+     * measure follows the Storybook deploy, not another app's. Default "storybook".
+     */
+    deployName?: string | undefined;
+    /** Install command. Default `npm ci`. */
+    install?: string | undefined;
+    /** Built Storybook only: the build command and its output folder. Default `npm run build-storybook`, storybook-static. */
+    buildCommand?: string | undefined;
+    storybookDir?: string | undefined;
+    /** What changes the Storybook (a push touching these measures again). Default MEASURE_DEFAULT_PATHS. */
+    paths?: readonly string[] | undefined;
+    /**
+     * The CLI command. Default `npx --yes <MEASURE_CLI_PACKAGE>`. This repository runs its own build
+     * (`node packages/cli/dist/index.js`), with `prepare` building it.
+     */
+    cli?: string | undefined;
+    /** Commands run after the install, before the measure (this repository builds the CLI). */
+    prepare?: string | undefined;
+    /** Node: a version, or `file:<path>` for node-version-file. Default 20. */
+    node?: string | undefined;
+    /** The header comment. Default: the template's, for teams. */
+    header?: string | undefined;
+}
+/**
+ * The options a team's bridge.config.json gives (parsed JSON, any shape): its default branch, its deployed Storybook
+ * (previews.production.storybook) and what changes the Storybook (the folder of its components, its tokens, the
+ * Storybook config). Missing parts are left to the defaults.
+ */
+export declare function measureWorkflowOptionsFromConfig(config: unknown): MeasureWorkflowOptions;
+/** The comment teams read at the top of the file: what it does, when, with which token, and the optional secret. */
+export declare const MEASURE_WORKFLOW_HEADER = "# Bridge measure: keeps the measure of your components fresh, so Claude can fix what differs in Figma.\n# Copy it to .github/workflows/bridge-measure.yml in your design system repository, or let Bridge add it: Studio, Settings,\n# For developers, Set up automatic measure (a pull request), or `npx @bridge-ds/cli measure setup`.\n#\n# It measures what your Storybook really draws (`bridge specs --measure`, headless Chrome): every variant at rest, on\n# hover, pressed and disabled, the CSS variables behind each value, and a screenshot of each. It publishes\n# measured-specs.json and measured-shots/ to the `bridge-requests` branch, next to figma-fidelity.json (the Figma plugin's\n# Compare with code). The Claude fix tools, the Figma plugin (\"Ask Claude to fix it\") and Studio read it there.\n# It commits only when the measure changed.\n#\n# When: after each deploy of your Storybook (deployed Storybook), or on each push to the default branch that changes it\n# (built here), every Monday as a fallback, and by hand (Actions, Bridge measure, Run workflow).\n#\n# Token: only the GITHUB_TOKEN of this run, with `contents: write` to push the `bridge-requests` branch. Your\n# default branch is never written. No secret to add.\n# A Storybook behind a login: set it up without an address (`npx @bridge-ds/cli measure setup --build`), the run then\n# builds Storybook itself. If installing needs a private registry, add an NPM_TOKEN repository secret (optional); the\n# install step passes it as NODE_AUTH_TOKEN.\n# Docs: https://bridge.floriangouloubi.com/docs/automatic-measure/";
+/** The workflow YAML. */
+export declare function measureWorkflowYaml(o?: MeasureWorkflowOptions): string;

package/dist/measured-only.d.ts

@@ -20,6 +20,8 @@ export type MeasuredShots = Record<string, Record<string, VariantShot>>;
 /** Every set the measure can give, by component (the last segment of a story's title: "Figma variants/Radio" is Radio). */
 export declare function specsFromMeasure(file: MeasuredSpecsFile | FixedMeasuredSpecsFile, opts?: {
     known?: ((path: string) => boolean) | undefined;
+    /** One set only (its name, compared like the fix tools compare it): what one component's gap case needs. */
+    only?: string | undefined;
 }): {
     specs: ComponentSpecsFile;
     report: MeasuredOnlyReport;

package/dist/node/index.js

@@ -2,11 +2,11 @@ import { execFile, execFileSync } from "node:child_process";
 import { mkdtemp, rm, mkdir, writeFile, lstat, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve, relative, dirname, sep, posix } from "node:path";
-import { bo as assertSafeBranch, c as collectHistory, p as packageDirCandidates, a as parseChangelog, m as mergeReleases, r as releasesFromTags, b as buildReport, de as prNumberFromSubject, dE as specHash, e9 as validateComponentSpec, K as hashSpec, cn as iconComponentName, F as variantKeyOf, e3 as tokenCssVar, aG as COMPONENT_SPECS_VERSION, J as COLOR_FIELDS, dM as suggestionAppliedComment, a1 as gitBlobSha, dc as planSuggestionApply, aq as normalizeRepoPath, dB as sharedTokenPrefix, e6 as tokenVariablePath, ej as withSrgbColors, dH as storybookIframeUrl, cX as parseBoxShadow } from "../repo-source-m0Tc603o.js";
-import { aV, C, c4, cJ, I, c_, H } from "../repo-source-m0Tc603o.js";
-import { K as selectTokenFiles, ag as globToRegExp, N as loadConfig, L as LayeredTokenSet, V as CONFIG_FILE, $ as layoutOptions, a0 as buildTokenSet, b9 as defaultContext, B as resolve$1, ae as slugify, c2 as protectedBranchesOf, aS as baseBranchOf } from "../prod-branch-Bdx_2bRQ.js";
+import { bp as assertSafeBranch, c as collectHistory, p as packageDirCandidates, a as parseChangelog, m as mergeReleases, r as releasesFromTags, b as buildReport, di as prNumberFromSubject, dI as specHash, ef as validateComponentSpec, K as hashSpec, cp as iconComponentName, F as variantKeyOf, e9 as tokenCssVar, aG as COMPONENT_SPECS_VERSION, J as COLOR_FIELDS, dQ as suggestionAppliedComment, a2 as gitBlobSha, dg as planSuggestionApply, aq as normalizeRepoPath, dF as sharedTokenPrefix, ec as tokenVariablePath, ep as withSrgbColors, dL as storybookIframeUrl, c_ as parseBoxShadow } from "../repo-source-CshjjC7x.js";
+import { aV, C, c6, cL, I, d1, H } from "../repo-source-CshjjC7x.js";
+import { K as selectTokenFiles, ah as globToRegExp, N as loadConfig, L as LayeredTokenSet, V as CONFIG_FILE, a0 as layoutOptions, a1 as buildTokenSet, b9 as defaultContext, B as resolve$1, af as slugify, c2 as protectedBranchesOf, _ as baseBranchOf } from "../prod-branch-CJZwMfVD.js";
 import { statSync, readFileSync, existsSync, writeFileSync, readdirSync } from "node:fs";
-import { i as isAuditable, Q as planCssFixes, O as parseAllowlist, d as DesignSystemIndex, l as buildAuditReport, o as compareWithBaseline, b as AUDIT_IGNORE_DIRS } from "../report-DFPKygfk.js";
+import { i as isAuditable, Q as planCssFixes, O as parseAllowlist, d as DesignSystemIndex, l as buildAuditReport, o as compareWithBaseline, b as AUDIT_IGNORE_DIRS } from "../report-CE-jHAuw.js";
 import ts from "typescript";
 function git(root, args, opts = {}) {
   return new Promise((resolve2, reject) => {
@@ -5183,7 +5183,10 @@ function measuredToSpec(m, o = {}) {
   if (!m.root) return out;
   const used = /* @__PURE__ */ new Set();
   const idFor = (n, isRoot, inherited) => {
-    if (isRoot) return "root";
+    if (isRoot) {
+      used.add("root");
+      return "root";
+    }
     const cls = (n.classes ?? []).map(localClassName).find((c) => /^[A-Za-z]/.test(c) && c.length < 40 && !isUtilityClass(c));
     let base = cls ?? (n.pseudo ? `${inherited ?? "root"}-${n.pseudo}` : n.kind === "text" ? inherited ? `${inherited}-text` : "text" : n.kind === "icon" ? "icon" : n.tag);
     base = base.replace(/[^A-Za-z0-9-]+/g, "-").toLowerCase() || "part";
@@ -5458,7 +5461,7 @@ export {
   draftedCodeHash,
   draftedSpec,
   entryFor,
-  c4 as evalCalc,
+  c6 as evalCalc,
   expandDecl,
   fileDiff,
   findDesignSystemRoot,
@@ -5485,7 +5488,7 @@ export {
   localRepoRef,
   localTags,
   markMeasuredRoot,
-  cJ as markUsedTokens,
+  cL as markUsedTokens,
   matchComplex,
   measureRendered,
   measureStory,
@@ -5499,7 +5502,7 @@ export {
   overridesDirOf,
   I as pairParts,
   parseCssModule,
-  c_ as parseMeasuredSpecsFile,
+  d1 as parseMeasuredSpecsFile,
   parseSelector,
   parseTransitions,
   pickStoriesToMeasure,