@elabs-ai/components-flow 4.1.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elabs-ai/components-flow",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "@xyflow/react": "^12.11.1",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "@elabs-ai/components-tokens": "4.1.0",
-    "@elabs-ai/components-ui": "4.1.0"
+    "@elabs-ai/components-tokens": "4.2.0",
+    "@elabs-ai/components-ui": "4.2.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
@@ -51,11 +51,11 @@
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^3.0.2",
-    "@elabs-ai/components-tokens": "4.1.0",
-    "@elabs-ai/components-icons": "4.1.0",
     "@elabs-ai/components-eslint-config": "0.1.0",
-    "@elabs-ai/components-ui": "4.1.0",
-    "@elabs-ai/components-typescript-config": "0.1.0"
+    "@elabs-ai/components-icons": "4.2.0",
+    "@elabs-ai/components-tokens": "4.2.0",
+    "@elabs-ai/components-typescript-config": "0.1.0",
+    "@elabs-ai/components-ui": "4.2.0"
   },
   "scripts": {
     "build": "tsup",

package/src/__contract__/inspector-panel.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for InspectorPanel (`packages/flow/src/inspector-panel/inspector-panel.tsx`), derived from its
+ * `Default` story (packages/flow/src/inspector-panel/inspector-panel.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../inspector-panel/inspector-panel.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `flow-inspectorpanel--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("InspectorPanel contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="inspector-panel" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="inspector-panel"]')).not.toBeNull();
+  });
+});

package/src/__contract__/legend.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for Legend (`packages/flow/src/legend/legend.tsx`), derived from its
+ * `Default` story (packages/flow/src/legend/legend.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../legend/legend.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `flow-legend--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("Legend contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="legend" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="legend"]')).not.toBeNull();
+  });
+});

package/src/flow-mini-map/flow-mini-map.stories.tsx

@@ -135,6 +135,23 @@ export const Default: Story = {
       return (hi! + 0.05) / (lo! + 0.05);
     };
 
+    // Measure the SETTLED paint, not the frame the theme switched in. The preview's
+    // `ThemeBoundary` writes `data-theme` in an effect, after the canvas has already
+    // rendered once under the `:root` (light) fallback. The storybook Vitest project runs
+    // with `reducedMotion: "reduce"`, and the tokens' reduced-motion backstop clamps
+    // `transition-duration` to 0.01ms on EVERY element — whose `transition-property`
+    // defaults to `all` — so the light→dark swap becomes a one-frame colour transition.
+    // Read synchronously, `getComputedStyle` still returns the transition's START value
+    // (the light panel's white) while the node rects, mounted after the switch, are
+    // already dark: a false 2.47:1 in the dark theme only. Awaiting the running
+    // transitions on the panel and its rects reads what the browser actually paints.
+    await Promise.all(
+      minimap.getAnimations({ subtree: true }).map((animation) =>
+        // A transition superseded by another change rejects `finished`; the settled
+        // value is still what the readback below measures.
+        animation.finished.catch(() => undefined),
+      ),
+    );
     const panelBackground = getComputedStyle(minimap).backgroundColor;
 
     // The whole point of this helper is that a blank minimap must FAIL the check — lock

package/src/inspector-panel/inspector-panel.tsx

@@ -1,5 +1,5 @@
 import { type CSSProperties, type ReactNode } from "react";
-import { Reveal, useCollapsiblePanel } from "@elabs-ai/components-ui";
+import { Reveal, useCollapsiblePanel, useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
 const INSPECTOR_PANEL_WIDTH = "18rem";
@@ -41,10 +41,10 @@ export interface InspectorPanelProps {
  * motion safe) when `open`/`defaultOpen` drive it.
  */
 export function InspectorPanel({
-  title = "Inspector",
+  title,
   children,
   onClose,
-  emptyMessage = "Select a node to see its details.",
+  emptyMessage,
   hasSelection = true,
   selectionKey,
   open,
@@ -54,6 +54,9 @@ export function InspectorPanel({
   width = INSPECTOR_PANEL_WIDTH,
   className,
 }: InspectorPanelProps) {
+  const { t } = useLocale();
+  const resolvedTitle = title ?? t("flow.inspectorPanel.title");
+  const resolvedEmptyMessage = emptyMessage ?? t("flow.inspectorPanel.emptyMessage");
   const panel = useCollapsiblePanel({
     side,
     open,
@@ -84,11 +87,11 @@ export function InspectorPanel({
         {/* Detail-tier surface: raised `card` — robust across themes (#193). */}
         <div className="flex h-full w-full flex-col bg-card">
           <div className="flex items-center justify-between border-b px-4 py-3">
-            <h3 className="text-body font-semibold text-foreground">{title}</h3>
+            <h3 className="text-body font-semibold text-foreground">{resolvedTitle}</h3>
             {onClose ? (
               <button
                 type="button"
-                aria-label="Close inspector"
+                aria-label={t("flow.inspectorPanel.close")}
                 onClick={onClose}
                 className="rounded-sm p-1 text-muted-foreground hover:text-foreground focus-ring"
               >
@@ -129,7 +132,7 @@ export function InspectorPanel({
             </Reveal>
           ) : (
             <div tabIndex={0} className="focus-ring flex-1 overflow-y-auto p-4 text-body">
-              <p className="text-muted-foreground">{emptyMessage}</p>
+              <p className="text-muted-foreground">{resolvedEmptyMessage}</p>
             </div>
           )}
         </div>

package/src/legend/legend.test.tsx

@@ -1,3 +1,4 @@
+import { LocaleProvider } from "@elabs-ai/components-ui";
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 import { computeEdgeWeightScale, type WeightedEdgeLike } from "../flow-weighted-edge/weight-scale";
@@ -212,4 +213,14 @@ describe('Legend variant="scale", kind="color"', () => {
     });
     expect(group).toHaveAttribute("tabindex", "0");
   });
+
+  it("formats the default tick label with the active LocaleProvider locale, not the host locale", () => {
+    render(
+      <LocaleProvider locale="de-DE">
+        <Legend variant="scale" kind="color" domain={[0, 1000]} />
+      </LocaleProvider>,
+    );
+    // de-DE groups thousands with a period, never a comma.
+    expect(screen.getByText("1.000")).toBeInTheDocument();
+  });
 });

package/src/legend/legend.tsx

@@ -1,3 +1,4 @@
+import { useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { computeEdgeWeightScale, type WeightedEdgeLike } from "../flow-weighted-edge/weight-scale";
 
@@ -33,7 +34,11 @@ export interface LegendScaleProps {
   kind: "width" | "color";
   /** `[min, max]` of the underlying value the ramp represents. */
   domain: [number, number];
-  /** Formats a domain value for display at a tick. @default `(v) => v.toLocaleString()` */
+  /**
+   * Formats a domain value for display at a tick.
+   * @default the active `LocaleProvider` locale's `formatNumber` (host locale
+   * when no provider is mounted) — never a hardcoded `toLocaleString()`.
+   */
   format?: (value: number) => string;
   /**
    * Sample count for `kind: "width"`: `"minmax"` draws a min/max pair of
@@ -51,8 +56,6 @@ export interface LegendScaleProps {
 
 export type LegendProps = LegendCategoricalProps | LegendScaleProps;
 
-const defaultFormat = (value: number): string => value.toLocaleString();
-
 /**
  * Small legend mapping colors/types to labels for a canvas or chart
  * (`variant: "categorical"`, the default), or — via `variant="scale"` — a
@@ -121,16 +124,21 @@ function scaleKindLabel(kind: "width" | "color"): string {
 function LegendScale({
   kind,
   domain,
-  format = defaultFormat,
+  format,
   ticks = "minmax",
   title,
   className,
 }: LegendScaleProps) {
+  // The active `LocaleProvider` locale, not a hardcoded `toLocaleString()` —
+  // otherwise a `de-DE`-configured app still reads the domain ticks in the
+  // browser's host locale.
+  const { formatNumber } = useLocale();
+  const format_ = format ?? formatNumber;
   const [min, max] = domain;
   // e.g. "Edge width scale, 2 to 48, minimum to maximum" — a single accessible
   // name for the whole reading key, since it is one keyboard tab stop, not one
   // per tick.
-  const ariaLabel = `Edge ${scaleKindLabel(kind)} scale, ${format(min)} to ${format(max)}, minimum to maximum`;
+  const ariaLabel = `Edge ${scaleKindLabel(kind)} scale, ${format_(min)} to ${format_(max)}, minimum to maximum`;
 
   return (
     <div
@@ -145,9 +153,9 @@ function LegendScale({
     >
       {title ? <div className="text-body font-medium text-foreground">{title}</div> : null}
       {kind === "width" ? (
-        <LegendScaleWidth domain={domain} format={format} ticks={ticks} />
+        <LegendScaleWidth domain={domain} format={format_} ticks={ticks} />
       ) : (
-        <LegendScaleColor domain={domain} format={format} />
+        <LegendScaleColor domain={domain} format={format_} />
       )}
     </div>
   );