@bridge-ds/core 0.5.0 → 0.6.0

package/dist/component-spec.d.ts

@@ -5,30 +5,37 @@ export declare const DEFAULT_COMPONENT_SPECS_FILE = "packages/react/component-sp
 /**
  * A Figma-side property a CSS declaration maps to.
  * Frames: fill (background-color), stroke and stroke weights (border), cornerRadius (border-radius), paddings, itemSpacing
- * (gap), sizes. Text: textFill (color), font family, size, weight, line height, letter spacing.
+ * (gap), sizes. Text: textFill (color), font family, size, weight, line height, letter spacing, and textDecoration (a
+ * keyword, "UNDERLINE" or "STRIKETHROUGH", not a token).
  */
-export type SpecField = 'fill' | 'stroke' | 'strokeWeight' | 'strokeTopWeight' | 'strokeRightWeight' | 'strokeBottomWeight' | 'strokeLeftWeight' | 'cornerRadius' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'itemSpacing' | 'width' | 'height' | 'minWidth' | 'minHeight' | 'textFill' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'letterSpacing';
+export type SpecField = 'fill' | 'stroke' | 'strokeWeight' | 'strokeTopWeight' | 'strokeRightWeight' | 'strokeBottomWeight' | 'strokeLeftWeight' | 'cornerRadius' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'itemSpacing' | 'counterAxisSpacing' | 'width' | 'height' | 'minWidth' | 'minHeight' | 'opacity' | 'textFill' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'letterSpacing' | 'textDecoration';
 export declare const SPEC_FIELDS: readonly SpecField[];
 /** Fields whose token must be a color. */
 export declare const COLOR_FIELDS: ReadonlySet<SpecField>;
 /**
- * A token path ("button.primary.bg"), a literal zero (`padding: 0`), null: no paint (`transparent`), or a calc() of token
- * paths ("calc(space.2 + space.0-5)", operators + - * / and px numbers): resolved to a number, set but not bound.
+ * A token path ("button.primary.bg"), a literal number (`padding: 0`, a unitless `stroke-width: 3` or `opacity: 0.5`),
+ * null: no paint (`transparent`), or a calc() of token paths ("calc(space.2 + space.0-5)", operators + - * / and px
+ * numbers): resolved to a number, set but not bound.
  */
-export type SpecValue = string | 0 | null;
+export type SpecValue = string | number | null;
 export interface SpecLayout {
     direction: 'HORIZONTAL' | 'VERTICAL';
     /** justify-content. */
     primary: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN';
     /** align-items. STRETCH: children fill the cross axis. */
     counter: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH';
+    /** `flex-direction: row-reverse | column-reverse`: children are drawn in reverse order. */
+    reverse?: boolean | undefined;
+    /** `flex-wrap: wrap` on a row: items wrap to new lines (Figma auto layout wrap). */
+    wrap?: boolean | undefined;
 }
 export interface SpecPart {
     /** Stable id inside the component ("root", "label", "icon-start"). Figma layers keep it in plugin data. */
     id: string;
     /** Layer name in Figma. */
     name: string;
-    kind: 'frame' | 'text' | 'icon';
+    /** vector: an inline SVG drawn from the variant's `vectors` markup (a spinner arc, a progress ring). */
+    kind: 'frame' | 'text' | 'icon' | 'vector';
     /** Parent part id; undefined for the root (the variant itself). */
     parent?: string | undefined;
     /** CSS module class the part is styled by ("Button.module.css .label"), for people reading the spec. */
@@ -42,11 +49,44 @@ export interface SpecPart {
     clip?: boolean | undefined;
     /** Root only: block-level in code (display block, flex or grid, or width 100%), so it fills its container. Figma draws it at a fixed width. */
     fill?: boolean | undefined;
+    /** Text parts with no TEXT property (content written in code, like a group's option labels): the characters drawn. */
+    characters?: string | undefined;
+    /**
+     * Positioned over its parent instead of flowing in its auto layout (an avatar photo over its initials): `position:
+     * absolute` with `inset: 0`, or `width` and `height` 100%. Drawn as an absolute child that fills its parent.
+     */
+    cover?: boolean | undefined;
+    /**
+     * `position: absolute` with token offsets (a dialog's close button): out of the auto layout, pinned to the parent's
+     * edges by these offsets (top, right, bottom, left).
+     */
+    pin?: {
+        top?: SpecValue;
+        right?: SpecValue;
+        bottom?: SpecValue;
+        left?: SpecValue;
+    } | undefined;
+    /** `width: 100%` or `height: 100%` in a parent of that size: Fill container on that axis. */
+    stretch?: {
+        width?: boolean;
+        height?: boolean;
+    } | undefined;
+    /** A value indicator (a progress fill): this share of its parent's width, from the component's value. */
+    fraction?: number | undefined;
+    /**
+     * A thumb placed at the component's value (a slider's): out of the auto layout, its center at this share of its
+     * parent's width, centered on the parent's height.
+     */
+    at?: number | undefined;
+    /** `flex: 1` in code: takes the free space along its parent's auto layout direction (Figma "Fill container"). */
+    grow?: boolean | undefined;
     /**
      * A swappable part: drawn as an instance of a generated component ("Icon/Plus", "Slot/Media") and swapped through an
      * INSTANCE_SWAP property. Icon parts swap between every icon of `icons`; content slots between `options`.
      */
     swap?: SpecSwap | undefined;
+    /** Icon parts whose icon is written in code (a checkbox's check mark): an instance of this icon, with no property. */
+    icon?: string | undefined;
 }
 export interface SpecSwap {
     /** INSTANCE_SWAP property name ("Icon", "Icon start", "Body"). */
@@ -117,6 +157,19 @@ export interface SpecVariant {
     values: Record<string, Partial<Record<SpecField, SpecValue>>>;
     /** Swappable part id -> the component this variant shows by default ("Icon/Plus", "Slot/Media"). */
     slots?: Record<string, string> | undefined;
+    /** Parts this variant does not show (`display: none`, `opacity: 0` or `scale(0)` in this state): hidden layers. */
+    hidden?: string[] | undefined;
+    /** Parts whose auto layout differs from the part's own in this variant (a switch thumb at the end when on). */
+    layout?: Record<string, SpecLayout> | undefined;
+    /** Vector parts: the SVG this variant draws and the stroke token of each shape, in order. */
+    vectors?: Record<string, SpecVector> | undefined;
+    /** Absolute parts placed differently in this variant (offsets from the parent's edges, like SpecPart.pin). */
+    pins?: Record<string, NonNullable<SpecPart['pin']>> | undefined;
+}
+/** An inline SVG part: markup with literal geometry (strokes painted #000000) and the token bound to each shape's stroke. */
+export interface SpecVector {
+    svg: string;
+    strokes: SpecValue[];
 }
 /** A declaration, prop or part that has no Figma equivalent in this version, with the reason. */
 export interface SpecUnmapped {
@@ -127,6 +180,26 @@ export interface SpecUnmapped {
 }
 export interface ComponentSpec {
     name: string;
+    /** Component folder the set comes from, when it is not the set's name (Radio comes from RadioGroup). */
+    component?: string | undefined;
+    /** Props pinned for this set (`{ variant: 'circular' }` for Progress/Circular, a set per layer tree). */
+    fixed?: Record<string, string> | undefined;
+    /** A popup drawn open (`popup`), or the component without its popup (`without-popup`). */
+    view?: 'popup' | 'without-popup' | undefined;
+    /**
+     * Drafted with Claude, not generated: the generator cannot read this component, so its spec was written by hand from
+     * the code (packages/react/component-spec-overrides/<Name>.json, `"source": "drafted"`) and validated like a generated
+     * one. Shown in the plugin as "Drafted, check it". `stale`: the code it was drafted from changed since.
+     */
+    drafted?: {
+        reason: string;
+        stale?: boolean | undefined;
+    } | undefined;
+    /**
+     * The code example the set's content comes from (the docs preview or a component sandbox example): the element, its
+     * props and children, so the fidelity check renders the same thing. Not in the hash: it does not change the drawing.
+     */
+    example?: SpecExample | undefined;
     /** FNV-1a of everything else in the spec: unchanged hash, nothing to rebuild. */
     hash: string;
     /** Files it was read from, repo-relative. */
@@ -137,6 +210,12 @@ export interface ComponentSpec {
     variants: SpecVariant[];
     unmapped: SpecUnmapped[];
 }
+/** An element of a code example: component export name, literal props, children (texts or elements). */
+export interface SpecExample {
+    c: string;
+    p?: Record<string, unknown> | undefined;
+    children?: (string | SpecExample)[] | undefined;
+}
 export interface ComponentSpecsFile {
     version: number;
     /** Human note at the top of the file. */
@@ -147,12 +226,50 @@ export interface ComponentSpecsFile {
     iconStyle?: SpecIconStyle | undefined;
     /** Content components slots swap to. */
     slots?: SpecSlot[] | undefined;
+    /**
+     * Every component of the design system and whether it is in Figma: generated (its sets are in `components`),
+     * unsupported (with the generator's reason) or layout (no visual of its own: a layout helper, use auto layout).
+     * Undefined in files written before coverage was recorded.
+     */
+    coverage?: SpecCoverage[] | undefined;
 }
+export type CoverageStatus = 'generated' | 'drafted' | 'unsupported' | 'layout';
+export interface SpecCoverage {
+    /** Component folder name ("RadioGroup"). */
+    name: string;
+    status: CoverageStatus;
+    /** Plain reason, for unsupported, drafted and layout components ("opens a popup", "uses CSS grid"). */
+    reason?: string | undefined;
+    /** Sets generated from it, when they are not just its own name ("RadioGroup", "Radio"). */
+    sets?: string[] | undefined;
+}
+/**
+ * Coverage counts from a specs file: visual components (generated, drafted with Claude, unsupported), in Figma
+ * (generated + drafted), and layout helpers.
+ */
+export declare function coverageSummary(file: Pick<ComponentSpecsFile, 'coverage' | 'components'>): {
+    generated: number;
+    drafted: number;
+    inFigma: number;
+    visual: number;
+    layout: number;
+    total: number;
+    missing: SpecCoverage[];
+};
+/**
+ * Checks a component spec against the format (the schema every set follows, generated or drafted): axes and their
+ * variants (one per combination, no extra), properties, parts (one root, known parents in order, text and visibility
+ * properties that exist), each value's field and type, and, given `tokenTypes` (token path -> $type), that every token
+ * path exists and has a type the field takes. Returns the problems in plain language, none when the spec is valid.
+ */
+export declare function validateComponentSpec(spec: Omit<ComponentSpec, 'hash'> & {
+    hash?: string;
+}, tokenTypes?: Map<string, string>): string[];
 /** Figma component name of an icon: "Icon/Plus". */
 export declare const iconComponentName: (name: string) => string;
 /** FNV-1a, 32 bits, 8 hex digits. */
 export declare function specHash(text: string): string;
-/** Hash of a spec without its own hash field. */
+/** Hash of a spec without its own hash field (and without its code example, which does not change the drawing). */
 export declare function hashSpec(spec: Omit<ComponentSpec, 'hash'> | ComponentSpec): string;
 /** Figma variant name for a variant's props: "Variant=primary, Size=md, State=Default" (axis order). */
 export declare const variantName: (props: Record<string, string>) => string;

package/dist/explorations.d.ts

@@ -39,6 +39,8 @@ export interface Exploration {
     source?: ExplorationSource | undefined;
     /** The AI agent that started it ("claude"), when one did: the GitHub account alone cannot tell. */
     agent?: string | undefined;
+    /** A Jira ticket key ("DS-42"), first in the pull request title so Jira's GitHub integration links it. */
+    jira?: string | undefined;
 }
 /** "Denser data tables!" -> "denser-data-tables". Up to 40 characters, cut at a word boundary. Empty when nothing is left. */
 export declare function explorationSlug(name: string): string;

package/dist/fidelity-references.d.ts

@@ -0,0 +1,78 @@
+import { type ComponentSpec, type ComponentSpecsFile, type SpecExample, type SpecVariant } from './component-spec';
+export declare const FIGMA_REFERENCES_BRANCH = "bridge-visual";
+export declare const FIGMA_REFERENCES_DIR = "figma-references";
+export declare const FIGMA_REFERENCES_MANIFEST = "figma-references/manifest.json";
+/** Story id of packages/react/src/stories/FigmaReference.stories.tsx. */
+export declare const FIGMA_REFERENCE_STORY = "internal-figma-reference--variant";
+/** Width token of a block-level root in Figma (the plugin draws fill roots at this width: FILL_WIDTH_TOKEN). */
+export declare const FIGMA_FILL_WIDTH_TOKEN = "size.80";
+export type ReferencePseudo = 'hover' | 'active' | 'focus-visible';
+/** What the reference story renders for one variant. JSON, passed to the story as a string arg. */
+export interface ReferenceRender {
+    /** Export name of the component ("Button", "Card"). */
+    component: string;
+    /** Props from the variant axes and the default property values ("variant": "primary", "disabled": true). */
+    props: Record<string, unknown>;
+    /** Text children (the Label property) of a simple component. */
+    text?: string | undefined;
+    /** Compound parts, in order: export name and text ("CardHeader", "Header"). */
+    parts?: {
+        component: string;
+        text: string;
+    }[] | undefined;
+    /** Icon props -> Lucide icon name ("icon": "Pencil"). */
+    icons?: Record<string, string> | undefined;
+    /** Hover, pressed or focus, forced with the pseudo-states addon classes. */
+    pseudo?: ReferencePseudo | undefined;
+    /** Width token path of the frame the component sits in, for roots that fill their container. */
+    width?: string | undefined;
+    /**
+     * Children from the code example the set was drawn with (a table's rows, a form's fields): texts and design system
+     * elements with their props, icons by name. Replaces `text` and `parts`.
+     */
+    children?: (string | SpecExample)[] | undefined;
+}
+export type ReferencePlan = {
+    ok: true;
+    render: ReferenceRender;
+} | {
+    ok: false;
+    reason: string;
+};
+/** How to render one generated variant from code, or why it cannot be compared. */
+export declare function planReference(spec: ComponentSpec, variant: SpecVariant, file?: Pick<ComponentSpecsFile, 'slots'>): ReferencePlan;
+/** File name of a variant's image, stable and file safe: "button/size-md__state-default__variant-primary.png". */
+export declare function referenceImagePath(component: string, key: string): string;
+export type FigmaReferenceEntry = {
+    file: string;
+    width: number;
+    height: number;
+} | {
+    skipped: string;
+};
+export interface FigmaReferenceManifest {
+    version: 1;
+    tool: '@bridge-ds/visual';
+    createdAt: string;
+    /** Commit of the code the images were made from. */
+    sha: string;
+    /** Device pixels per CSS pixel, the scale the plugin exports Figma variants at. */
+    scale: number;
+    mode: {
+        brand: string;
+        theme: string;
+        density: string;
+    };
+    storyId: string;
+    components: Record<string, {
+        specHash: string;
+        variants: Record<string, FigmaReferenceEntry>;
+    }>;
+}
+/** Every variant of every spec with its render plan (the capture's to-do list). */
+export declare function planReferences(file: ComponentSpecsFile): {
+    component: string;
+    specHash: string;
+    key: string;
+    plan: ReferencePlan;
+}[];

package/dist/fidelity.d.ts

@@ -0,0 +1,138 @@
+/** An RGBA image, 4 bytes per pixel, row by row (ImageData, pngjs and canvas all use this layout). */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface CompareOptions {
+    /** Export scale of both images (device pixels per CSS pixel). Sizes are reported in CSS pixels. Default 2. */
+    scale?: number;
+    /**
+     * Color distance under which two pixels are the same, 0 to 1 (YIQ, as pixelmatch). Default 0.1: absorbs gamma
+     * and antialiasing ramps, catches a token swap (a gray one step away is about 0.12).
+     */
+    threshold?: number;
+    /**
+     * Neighborhood, in device pixels, searched for a matching pixel before one counts as different. Figma and Chrome
+     * rasterize text and curves differently (glyph hinting, subpixel positions, corner antialiasing): a pixel that has
+     * its twin within this distance is the same shape drawn half a pixel away. Default: one CSS pixel (= scale).
+     */
+    radius?: number;
+    /** Largest share of different pixels, in percent, that still matches. Default 3. */
+    maxPercent?: number;
+    /** Largest size difference per side, in CSS pixels, that still matches. Default 1. */
+    sizeTolerance?: number;
+    /** Also return the diff overlay. Default true. */
+    diffImage?: boolean;
+}
+export interface ImageCompareResult {
+    matches: boolean;
+    /** Different pixels in percent of the larger canvas, two decimals. */
+    percent: number;
+    differentPixels: number;
+    totalPixels: number;
+    /** CSS pixel sizes (image size divided by the scale, rounded). */
+    size: {
+        figma: Size;
+        code: Size;
+    };
+    sizeMatches: boolean;
+    /** The code image faded to gray with different pixels in red, on the larger canvas. */
+    diff?: RgbaImage | undefined;
+}
+export declare const FIDELITY_DEFAULTS: {
+    readonly scale: 2;
+    readonly threshold: 0.1;
+    readonly maxPercent: 3;
+    readonly sizeTolerance: 1;
+};
+/** YIQ squared distance between two opaque colors (pixelmatch's perceptual metric). */
+export declare function colorDelta(a: [number, number, number], b: [number, number, number]): number;
+/**
+ * Compares a Figma export with the code reference of the same variant. A pixel differs when its color is not found
+ * near the same place in the other image, in either direction: a shape drawn half a pixel away, or text rasterized
+ * a little differently, matches; a missing border, another color, other padding or a different size does not.
+ * Pixels outside the smaller image count as transparent: there, any visible color differs (a missing footer is a
+ * difference even when its gray is light).
+ */
+export declare function compareImages(figma: RgbaImage, code: RgbaImage, options?: CompareOptions): ImageCompareResult;
+export type FidelityVariantStatus = 'matches' | 'differs' | 'skipped';
+export interface FidelityVariantResult {
+    /** Variant key, as the plugin stores it ("Size=md, State=Default, Variant=primary"). */
+    key: string;
+    status: FidelityVariantStatus;
+    percent?: number | undefined;
+    size?: {
+        figma: Size;
+        code: Size;
+    } | undefined;
+    /** Skipped variants: why there is nothing to compare, in designer words. */
+    reason?: string | undefined;
+}
+export type FidelityComponentStatus = 'matches' | 'differs' | 'not-checked';
+export interface FidelityComponentResult {
+    component: string;
+    status: FidelityComponentStatus;
+    checked: number;
+    differing: number;
+    skipped: number;
+    /** The variant that differs most (or matches least well). */
+    worst?: {
+        key: string;
+        percent: number;
+        size: {
+            figma: Size;
+            code: Size;
+        };
+    } | undefined;
+    /** Not checked at all: why. */
+    reason?: string | undefined;
+    variants: FidelityVariantResult[];
+}
+export interface FidelityReport {
+    version: 1;
+    checkedAt: string;
+    /** Figma file the sets were exported from. */
+    file?: string | undefined;
+    /** Commit the code images were made from. */
+    reference: {
+        sha: string;
+        createdAt: string;
+    };
+    options: {
+        scale: number;
+        threshold: number;
+        radius: number;
+        maxPercent: number;
+        sizeTolerance: number;
+    };
+    components: FidelityComponentResult[];
+    summary: {
+        components: number;
+        matches: number;
+        differs: number;
+        notChecked: number;
+        variantsChecked: number;
+        variantsSkipped: number;
+    };
+}
+/** Rolls variant results up into one component result. */
+export declare function summarizeComponent(component: string, variants: FidelityVariantResult[], reason?: string): FidelityComponentResult;
+export declare function buildFidelityReport(input: {
+    components: FidelityComponentResult[];
+    reference: {
+        sha: string;
+        createdAt: string;
+    };
+    options?: CompareOptions;
+    file?: string;
+    now?: Date;
+}): FidelityReport;
+/** One variant's verdict: "Matches the code" or "Differs from the code: 12% of pixels, size 120x40 vs 118x40". */
+export declare function fidelityVerdict(v: Pick<FidelityVariantResult, 'status' | 'percent' | 'size' | 'reason'>): string;
+/** One component's line, from its worst variant. */
+export declare function fidelityComponentLine(c: FidelityComponentResult): string;

package/dist/index.d.ts

@@ -43,3 +43,5 @@ export * from './explorations';
 export * from './explorations-github';
 export * from './requests-github';
 export * from './component-spec';
+export * from './fidelity';
+export * from './fidelity-references';