@teambit/api-reference 1.0.1079 → 1.0.1081

package/api-compare.module.scss

@@ -3,248 +3,6 @@
   flex-direction: column;
   height: 100%;
   overflow: auto;
-  padding: 24px;
-  gap: 16px;
-}
-
-.summary {
-  display: flex;
-  gap: 12px;
-  align-items: center;
-  padding: 12px 16px;
-  background: var(--bit-bg-dent, #f6f6f6);
-  border-radius: 8px;
-  font-size: 13px;
-}
-
-.summaryDivider {
-  opacity: 0.3;
-  color: var(--bit-text-color-light, #6c707c);
-}
-
-.summaryBadge {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-  padding: 3px 10px;
-  border-radius: 12px;
-  font-weight: 500;
-  font-size: 12px;
-  white-space: nowrap;
-}
-
-.addedBadge {
-  composes: summaryBadge;
-  background: color-mix(in srgb, var(--bit-color-added, #2ea043) 15%, transparent);
-  color: var(--bit-color-added, #2ea043);
-}
-
-.removedBadge {
-  composes: summaryBadge;
-  background: color-mix(in srgb, var(--bit-color-removed, #f85149) 15%, transparent);
-  color: var(--bit-color-removed, #f85149);
-}
-
-.modifiedBadge {
-  composes: summaryBadge;
-  background: color-mix(in srgb, var(--bit-color-modified, #d29922) 15%, transparent);
-  color: var(--bit-color-modified, #d29922);
-}
-
-.changeList {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.sectionTitle {
-  margin: 16px 0 8px;
-  font-size: 12px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.5px;
-  color: var(--bit-text-color-light, #6c707c);
-}
-
-.diffEntry {
-  border: 1px solid var(--bit-border-color-lightest, #ededed);
-  border-radius: 8px;
-  overflow: hidden;
-}
-
-.diffEntryHeader {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  padding: 10px 16px;
-  cursor: pointer;
-  user-select: none;
-
-  &:hover {
-    background: var(--bit-bg-dent, #f6f6f6);
-  }
-}
-
-.statusBadge {
-  display: inline-flex;
-  align-items: center;
-  padding: 2px 8px;
-  border-radius: 4px;
-  font-weight: 600;
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-  flex-shrink: 0;
-  white-space: nowrap;
-}
-
-.statusAdded {
-  composes: statusBadge;
-  background: color-mix(in srgb, var(--bit-color-added, #2ea043) 15%, transparent);
-  color: var(--bit-color-added, #2ea043);
-}
-
-.statusRemoved {
-  composes: statusBadge;
-  background: color-mix(in srgb, var(--bit-color-removed, #f85149) 15%, transparent);
-  color: var(--bit-color-removed, #f85149);
-}
-
-.statusModified {
-  composes: statusBadge;
-  background: color-mix(in srgb, var(--bit-color-modified, #d29922) 15%, transparent);
-  color: var(--bit-color-modified, #d29922);
-}
-
-.exportName {
-  font-weight: 600;
-  font-size: 14px;
-  font-family: var(--bit-font-mono, monospace);
-  color: var(--bit-text-color-heavy, #2b2b2b);
-}
-
-.schemaType {
-  color: var(--bit-text-color-light, #6c707c);
-  font-size: 12px;
-}
-
-.impactBadge {
-  composes: summaryBadge;
-  margin-left: auto;
-  font-size: 11px;
-}
-
-.expandIcon {
-  color: var(--bit-text-color-light, #6c707c);
-  font-size: 10px;
-  transition: transform 0.2s;
-  flex-shrink: 0;
-}
-
-.expandIconOpen {
-  composes: expandIcon;
-  transform: rotate(90deg);
-}
-
-.diffEntryBody {
-  padding: 0 16px 16px;
-  border-top: 1px solid var(--bit-border-color-lightest, #ededed);
-}
-
-.detailsList {
-  list-style: none;
-  padding: 12px 0 0;
-  margin: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.detailItem {
-  display: flex;
-  align-items: flex-start;
-  gap: 8px;
-  font-size: 13px;
-  line-height: 1.5;
-  color: var(--bit-text-color-heavy, #2b2b2b);
-}
-
-.detailDot {
-  width: 7px;
-  height: 7px;
-  min-width: 7px;
-  border-radius: 50%;
-  margin-top: 6px;
-  flex-shrink: 0;
-}
-
-.dotBreaking {
-  composes: detailDot;
-  background: var(--bit-color-removed, #f85149);
-}
-
-.dotNonBreaking {
-  composes: detailDot;
-  background: var(--bit-color-added, #2ea043);
-}
-
-.dotPatch {
-  composes: detailDot;
-  background: var(--bit-color-modified, #d29922);
-}
-
-.detailDescription {
-  color: var(--bit-text-color-heavy, #2b2b2b);
-}
-
-.signatureBlock {
-  margin-top: 12px;
-  padding: 12px;
-  background: var(--bit-bg-dent, #f6f6f6);
-  border-radius: 6px;
-  font-family: var(--bit-font-mono, monospace);
-  font-size: 12px;
-  white-space: pre-wrap;
-  word-break: break-word;
-  line-height: 1.6;
-  color: var(--bit-text-color-heavy, #2b2b2b);
-}
-
-.signatureLabel {
-  font-weight: 600;
-  color: var(--bit-text-color-light, #6c707c);
-  margin-top: 12px;
-  margin-bottom: 4px;
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.5px;
-}
-
-.signatureRemoved {
-  composes: signatureBlock;
-  text-decoration: line-through;
-  opacity: 0.6;
-}
-
-.emptyState {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 100%;
-  color: var(--bit-text-color-light, #6c707c);
-  font-size: 14px;
-}
-
-.toggleSignatures {
-  background: none;
-  border: none;
-  color: var(--bit-accent-color, #0366d6);
-  font-size: 12px;
-  cursor: pointer;
-  padding: 4px 0;
-  margin-top: 12px;
-
-  &:hover {
-    text-decoration: underline;
-  }
+  padding: 16px 24px;
+  max-width: 980px;
 }

package/api-compare.section.tsx

@@ -2,12 +2,24 @@ import React from 'react';
 import type { Section } from '@teambit/component';
 import type { TabItem } from '@teambit/component.ui.component-compare.models.component-compare-props';
 import type { ChangeType } from '@teambit/component.ui.component-compare.models.component-compare-change-type';
+import type { ApiDiffInsight } from '@teambit/semantics.ui.api-diff-view';
 import { APICompare } from './api-compare';
 
 // Use string cast since the external ChangeType enum doesn't have API yet
 const ChangeTypeAPI = 'API' as unknown as ChangeType;
 
 export class APICompareSection implements TabItem, Section {
+  route: { path: string; element: React.ReactNode };
+
+  constructor(getInsights?: () => ApiDiffInsight[]) {
+    // built in the constructor (not a field initializer) so the element captures the
+    // getter regardless of class-field initialization order.
+    this.route = {
+      path: 'api/*',
+      element: <APICompare getInsights={getInsights} />,
+    };
+  }
+
   navigationLink = {
     href: 'api',
     children: 'API',
@@ -15,11 +27,6 @@ export class APICompareSection implements TabItem, Section {
 
   props = this.navigationLink;
 
-  route = {
-    path: 'api/*',
-    element: <APICompare />,
-  };
-
   order = 15;
   changeType = ChangeTypeAPI;
   id = 'api';

package/api-compare.tsx

@@ -1,202 +1,84 @@
 import React from 'react';
 import { useComponentCompare } from '@teambit/component.ui.component-compare.context';
-import type { APIDiffResult, APIDiffChange, APIDiffDetail } from './api-compare.types';
+import {
+  ComponentApiDiffSection,
+  ApiDiffSlimRow,
+  ApiDiffInsightProvider,
+  useApiDiff,
+} from '@teambit/semantics.ui.api-diff-view';
+import type { ApiDiffInsight } from '@teambit/semantics.ui.api-diff-view';
 import styles from './api-compare.module.scss';
 
-export type { APIDiffResult, APIDiffChange, APIDiffDetail };
+// single source of truth for the API diff model lives in api-diff-view.
+export type { APIDiffResult, APIDiffChange, APIDiffDetail } from '@teambit/semantics.ui.api-diff-view';
 
-function impactClass(impact: string): string {
-  switch (impact) {
-    case 'BREAKING':
-      return styles.removedBadge;
-    case 'NON_BREAKING':
-      return styles.addedBadge;
-    case 'PATCH':
-      return styles.modifiedBadge;
-    default:
-      return styles.summaryBadge;
-  }
-}
-
-function impactLabel(impact: string): string {
-  switch (impact) {
-    case 'BREAKING':
-      return 'Breaking';
-    case 'NON_BREAKING':
-      return 'Non-breaking';
-    case 'PATCH':
-      return 'Patch';
-    default:
-      return impact;
-  }
-}
-
-function getStatusClass(status: string): string {
-  switch (status) {
-    case 'ADDED':
-      return styles.statusAdded;
-    case 'REMOVED':
-      return styles.statusRemoved;
-    case 'MODIFIED':
-      return styles.statusModified;
-    default:
-      return styles.statusBadge;
-  }
-}
-
-function getStatusLabel(status: string): string {
-  switch (status) {
-    case 'ADDED':
-      return '+ Added';
-    case 'REMOVED':
-      return '- Removed';
-    case 'MODIFIED':
-      return '~ Modified';
-    default:
-      return status;
-  }
-}
-
-function dotClass(impact: string): string {
-  switch (impact) {
-    case 'BREAKING':
-      return styles.dotBreaking;
-    case 'NON_BREAKING':
-      return styles.dotNonBreaking;
-    default:
-      return styles.dotPatch;
-  }
-}
-
-function DetailItem({ detail }: { detail: APIDiffDetail }) {
-  return (
-    <li className={styles.detailItem}>
-      <span className={dotClass(detail.impact)} />
-      <span className={styles.detailDescription}>{detail.description}</span>
-    </li>
-  );
-}
-
-function APIDiffEntry({ change }: { change: APIDiffChange }) {
-  const [expanded, setExpanded] = React.useState(change.status === 'MODIFIED');
-  const [showSignatures, setShowSignatures] = React.useState(false);
+export type APICompareProps = {
+  /** resolved lazily at render time — slot registrations can land after the section is constructed */
+  getInsights?: () => ApiDiffInsight[];
+};
 
-  const hasBody =
-    change.status === 'MODIFIED'
-      ? (change.changes && change.changes.length > 0) || change.baseSignature || change.compareSignature
-      : change.baseSignature || change.compareSignature;
-
-  return (
-    <div className={styles.diffEntry}>
-      <div
-        className={styles.diffEntryHeader}
-        onClick={() => hasBody && setExpanded(!expanded)}
-        role="button"
-        tabIndex={0}
-        aria-expanded={hasBody ? expanded : undefined}
-        onKeyDown={(e) => {
-          if (e.key === 'Enter' || e.key === ' ') {
-            e.preventDefault();
-            hasBody && setExpanded(!expanded);
-          }
-        }}
-      >
-        <span className={getStatusClass(change.status)}>{getStatusLabel(change.status)}</span>
-        <span className={styles.exportName}>{change.exportName}</span>
-        <span className={styles.schemaType}>{change.schemaType}</span>
-        <span className={`${impactClass(change.impact)} ${styles.impactBadge}`}>{impactLabel(change.impact)}</span>
-        {hasBody && <span className={expanded ? styles.expandIconOpen : styles.expandIcon}>▶</span>}
-      </div>
-      {expanded && hasBody && (
-        <div className={styles.diffEntryBody}>
-          {change.status === 'MODIFIED' && change.changes && change.changes.length > 0 && (
-            <ul className={styles.detailsList}>
-              {change.changes.map((detail, i) => (
-                <DetailItem key={`${detail.changeKind}-${i}`} detail={detail} />
-              ))}
-            </ul>
-          )}
-          {change.status === 'MODIFIED' && (change.baseSignature || change.compareSignature) && (
-            <>
-              <button className={styles.toggleSignatures} onClick={() => setShowSignatures(!showSignatures)}>
-                {showSignatures ? '▼ Hide signatures' : '▶ Show signatures'}
-              </button>
-              {showSignatures && (
-                <>
-                  {change.baseSignature && (
-                    <div>
-                      <div className={styles.signatureLabel}>Base</div>
-                      <div className={styles.signatureRemoved}>{change.baseSignature}</div>
-                    </div>
-                  )}
-                  {change.compareSignature && (
-                    <div>
-                      <div className={styles.signatureLabel}>Compare</div>
-                      <div className={styles.signatureBlock}>{change.compareSignature}</div>
-                    </div>
-                  )}
-                </>
-              )}
-            </>
-          )}
-          {change.status === 'ADDED' && change.compareSignature && (
-            <div className={styles.signatureBlock}>{change.compareSignature}</div>
-          )}
-          {change.status === 'REMOVED' && change.baseSignature && (
-            <div className={styles.signatureRemoved}>{change.baseSignature}</div>
-          )}
-        </div>
-      )}
-    </div>
-  );
-}
-
-function ChangeSection({ title, changes }: { title: string; changes: APIDiffChange[] }) {
-  if (changes.length === 0) return null;
-
-  const sorted = [...changes].sort((a, b) => {
-    const order: Record<string, number> = { REMOVED: 0, MODIFIED: 1, ADDED: 2 };
-    return (order[a.status] ?? 3) - (order[b.status] ?? 3);
+/**
+ * the API tab of the single-component compare page. thin host around the same
+ * `ComponentApiDiffSection` the lane-compare API view uses — one implementation, two hosts.
+ * data comes from the compare context (fetched once by ComponentCompare).
+ */
+export function APICompare({ getInsights }: APICompareProps) {
+  const compareContext = useComponentCompare();
+  const baseModel = compareContext?.base?.model;
+  const compareModel = compareContext?.compare?.model;
+
+  // Prefer a diff already on the context — the legacy `ComponentCompare` fetches it once and sets
+  // it there. The redesign single-component page does NOT put it on its inline context, so we fetch
+  // on our own. This hook is only mounted when the API view is the active tab (the page renders the
+  // element on-demand), so lane-compare — which renders one panel per component and never mounts
+  // this tab — pays nothing.
+  const contextApiDiff = compareContext?.apiDiffResult;
+  const shouldSelfFetch = contextApiDiff === undefined;
+  const { result: fetchedApiDiff } = useApiDiff(baseModel?.id.toString(), compareModel?.id.toString(), {
+    skip: !shouldSelfFetch,
   });
+  const apiDiffResult = shouldSelfFetch ? fetchedApiDiff : contextApiDiff;
 
-  return (
-    <>
-      <h3 className={styles.sectionTitle}>{title}</h3>
-      <div className={styles.changeList}>
-        {sorted.map((change) => (
-          <APIDiffEntry key={`${change.visibility}-${change.status}-${change.exportName}`} change={change} />
-        ))}
-      </div>
-    </>
-  );
-}
+  // memoized so the insights context value keeps a stable identity — otherwise a fresh array every
+  // render would re-render every `useApiDiffInsights` consumer (incl. the React.memo'd ApiChangeBlock).
+  const insights = React.useMemo(() => getInsights?.(), [getInsights]);
 
-export function APICompare() {
-  const compareContext = useComponentCompare();
-  const apiDiffResult: APIDiffResult | null | undefined = (compareContext as any)?.apiDiffResult;
+  if (!compareContext) return null;
 
-  if (apiDiffResult === undefined) {
-    return <div className={styles.emptyState}>Loading API diff...</div>;
-  }
+  const id = (compareModel || baseModel)?.id;
+  if (!id) return null;
 
-  if (!apiDiffResult || !apiDiffResult.hasChanges) {
-    return <div className={styles.emptyState}>No API changes between these versions</div>;
-  }
+  const componentIdStr = id.toStringWithoutVersion();
+  const baseVersion = baseModel?.id.version;
+  const compareVersion = compareModel?.id.version;
 
-  const { publicChanges, internalChanges, added, removed, modified, breaking, impact } = apiDiffResult;
+  // no base (first version) or identical versions — nothing to diff, not a failure.
+  const nothingToCompare = apiDiffResult === null && (!baseVersion || baseVersion === compareVersion);
 
   return (
-    <div className={styles.apiCompareContainer}>
-      <div className={styles.summary}>
-        <span className={impactClass(impact)}>{impactLabel(impact)}</span>
-        <span className={styles.summaryDivider}>|</span>
-        {added > 0 && <span className={styles.addedBadge}>+{added} added</span>}
-        {removed > 0 && <span className={styles.removedBadge}>-{removed} removed</span>}
-        {modified > 0 && <span className={styles.modifiedBadge}>~{modified} modified</span>}
-        {breaking > 0 && <span className={styles.removedBadge}>{breaking} breaking</span>}
+    <ApiDiffInsightProvider insights={insights}>
+      <div className={styles.apiCompareContainer}>
+        {nothingToCompare ? (
+          <ApiDiffSlimRow
+            componentIdStr={componentIdStr}
+            displayName={id.fullName}
+            chip="nothing to compare"
+            detail={baseVersion ? 'both sides are the same version' : 'no base version to compare against'}
+            tone="ok"
+          />
+        ) : (
+          <ComponentApiDiffSection
+            componentIdStr={componentIdStr}
+            displayName={id.fullName}
+            baseId={baseModel?.id.toString()}
+            compareId={compareModel?.id.toString()}
+            baseVersion={baseVersion}
+            compareVersion={compareVersion}
+            result={apiDiffResult}
+            loading={apiDiffResult === undefined}
+          />
+        )}
       </div>
-      <ChangeSection title="Public API" changes={publicChanges} />
-      <ChangeSection title="Internal (non-exported)" changes={internalChanges} />
-    </div>
+    </ApiDiffInsightProvider>
   );
 }

package/api-reference.ui.runtime.tsx

@@ -87,8 +87,9 @@ export class APIReferenceUI {
     // register all default schema classes
     apiReferenceUI.registerSchemaClasses(() => Object.values(Schemas));
 
-    // register API compare tab in component compare
-    const apiCompareSection = new APICompareSection();
+    // register API compare tab in component compare. insights are resolved lazily —
+    // aspects can register them on componentCompareUI after this provider runs.
+    const apiCompareSection = new APICompareSection(() => componentCompareUI.getApiDiffInsights());
     componentCompareUI.registerNavigation(apiCompareSection);
     componentCompareUI.registerRoutes([apiCompareSection.route]);
 

package/dist/api-compare.d.ts

@@ -1,4 +1,13 @@
 import React from 'react';
-import type { APIDiffResult, APIDiffChange, APIDiffDetail } from './api-compare.types';
-export type { APIDiffResult, APIDiffChange, APIDiffDetail };
-export declare function APICompare(): React.JSX.Element;
+import type { ApiDiffInsight } from '@teambit/semantics.ui.api-diff-view';
+export type { APIDiffResult, APIDiffChange, APIDiffDetail } from '@teambit/semantics.ui.api-diff-view';
+export type APICompareProps = {
+    /** resolved lazily at render time — slot registrations can land after the section is constructed */
+    getInsights?: () => ApiDiffInsight[];
+};
+/**
+ * the API tab of the single-component compare page. thin host around the same
+ * `ComponentApiDiffSection` the lane-compare API view uses — one implementation, two hosts.
+ * data comes from the compare context (fetched once by ComponentCompare).
+ */
+export declare function APICompare({ getInsights }: APICompareProps): React.JSX.Element | null;