@astryxdesign/lab 0.7.1-canary.ff40b78 → 0.7.2-canary.c68f5e8

package/blocks/DiffViewerShowcase.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Unified diff from a patch',
+  displayName: 'Unified diff from a patch',
+  description:
+    'A patch parsed with parseUnifiedDiff and rendered in unified or split view. Clicking a line number selects that line and opens an annotation row under it, the way a review comment would appear.',
+  exampleFor: 'DiffViewer',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'DiffViewer',
+    'Button',
+    'HStack',
+    'StackItem',
+    'VStack',
+    'Text',
+  ],
+};

package/blocks/DiffViewerShowcase.tsx

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A unified diff string parsed with parseUnifiedDiff
+ * @output One DiffViewer with a unified/split toggle and click-to-comment line numbers
+ * @position Lab DiffViewer's docsite showcase and copyable CLI block
+ */
+
+import {useState} from 'react';
+import {
+  DiffViewer,
+  parseUnifiedDiff,
+  type DiffViewerLineRef,
+} from '@astryxdesign/lab';
+import {Button} from '@astryxdesign/core/Button';
+import {HStack, StackItem, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+const PATCH = `diff --git a/src/cart/total.ts b/src/cart/total.ts
+--- a/src/cart/total.ts
++++ b/src/cart/total.ts
+@@ -1,9 +1,11 @@
+ import type {CartItem} from './types';
++import {roundCurrency} from '../money';
+ 
+-export function cartTotal(items: CartItem[], discount = 0) {
+-  let total = 0;
+-  for (const item of items) {
+-    total += item.price * item.quantity * (1 - discount);
+-  }
+-  return total;
++export function cartTotal(items: CartItem[], discount = 0): number {
++  const subtotal = items.reduce(
++    (sum, item) => sum + item.price * item.quantity,
++    0,
++  );
++  return roundCurrency(subtotal * (1 - discount));
+ }
+`;
+
+const [FILE] = parseUnifiedDiff(PATCH);
+
+export default function DiffViewerShowcase() {
+  const [viewMode, setViewMode] = useState<'unified' | 'split'>('unified');
+  const [selected, setSelected] = useState<DiffViewerLineRef | null>(null);
+
+  return (
+    <VStack gap={3}>
+      <HStack gap={2} vAlign="center">
+        <StackItem size="fill">
+          <Text type="supporting" color="secondary">
+            {selected == null
+              ? 'Click a line number to select a line.'
+              : `Selected ${selected.side} line ${selected.lineNumber}`}
+          </Text>
+        </StackItem>
+        <Button
+          label={viewMode === 'unified' ? 'Split view' : 'Unified view'}
+          variant="secondary"
+          onClick={() =>
+            setViewMode(mode => (mode === 'unified' ? 'split' : 'unified'))
+          }
+        />
+      </HStack>
+      <DiffViewer
+        file={FILE}
+        viewMode={viewMode}
+        onLineNumberClick={ref => setSelected(ref)}
+        renderLineAnnotation={ref =>
+          selected != null &&
+          ref.side === selected.side &&
+          ref.lineNumber === selected.lineNumber ? (
+            <Text>{`Comment on ${ref.side} line ${ref.lineNumber}`}</Text>
+          ) : null
+        }
+      />
+    </VStack>
+  );
+}

package/dist/DiffViewer/DiffViewer.d.ts

@@ -0,0 +1,132 @@
+import { type MouseEvent, type ReactNode, type Ref } from 'react';
+import type { BaseProps } from '@astryxdesign/core';
+import { type SyntaxThemeDefinition } from '@astryxdesign/core/theme/syntax';
+import type { DiffViewerFile, DiffViewerLineRef } from './diffTypes';
+/** How hunks are laid out: one column, or old and new side by side. */
+export type DiffViewerViewMode = 'unified' | 'split';
+/**
+ * How a changed line is marked beside its code: `classic` `+`/`-` glyphs,
+ * `bars` (a solid bar for added lines and a dashed one for removed lines), or
+ * `none`. Screen readers hear "Added"/"Removed" in every mode.
+ */
+export type DiffViewerChangeIndicator = 'classic' | 'bars' | 'none';
+/**
+ * How finely to highlight what changed inside a removed line and the added
+ * line that replaced it: by `word`, by `char`acter, or `none`.
+ */
+export type DiffViewerInlineHighlight = 'word' | 'char' | 'none';
+export interface DiffViewerProps extends BaseProps<HTMLDivElement> {
+    /** Ref forwarded to the root element. */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * The file to render. Build one with `parseUnifiedDiff(patch)` (one per
+     * file in the patch) or `createDiffFile({oldValue, newValue})`.
+     */
+    file: DiffViewerFile;
+    /**
+     * `unified` shows one column with removed lines above their replacements;
+     * `split` shows the old file on the left and the new file on the right,
+     * pairing each removed line with the added line that replaced it. The hunk
+     * area reads left-to-right in every page direction, like a code editor;
+     * the file header and annotation content follow the page, and annotation
+     * rows scroll with the code.
+     * @default 'unified'
+     */
+    viewMode?: DiffViewerViewMode;
+    /**
+     * Syntax-highlighting language. Defaults to one inferred from the file's
+     * extension; unknown extensions render as plain text.
+     */
+    language?: string;
+    /**
+     * Show the old and new line-number gutters.
+     * @default true
+     */
+    hasLineNumbers?: boolean;
+    /**
+     * Wrap long lines instead of scrolling them horizontally. Unwrapped, line
+     * numbers and change indicators stay pinned while the code scrolls; in
+     * split view each side is its own scroller, the split stays fixed at half
+     * and half, and the two sides scroll sideways in lockstep. While code
+     * overflows sideways, sideways overscroll (elastic bounce, swipe
+     * navigation) is off.
+     * @default false
+     */
+    isWrapped?: boolean;
+    /**
+     * How changed lines are marked beside their code.
+     * @default 'classic'
+     */
+    changeIndicator?: DiffViewerChangeIndicator;
+    /**
+     * Highlight the changed words (or characters) inside each removed line and
+     * the added line that replaced it. Lines that share nothing but whitespace
+     * get no inline highlight; the row tint already marks them.
+     * @default 'word'
+     */
+    inlineHighlight?: DiffViewerInlineHighlight;
+    /**
+     * Tint the rows of added and removed lines. Without it only the change
+     * indicator, the line numbers, and the inline highlight mark a change.
+     * @default true
+     */
+    hasChangeBackground?: boolean;
+    /**
+     * Make the file header a disclosure that hides and shows the hunks. Needs a
+     * file path to name the control.
+     * @default true
+     */
+    isCollapsible?: boolean;
+    /** Controlled collapsed state. Pair with `onCollapsedChange`. */
+    isCollapsed?: boolean;
+    /**
+     * Initial collapsed state when uncontrolled.
+     * @default false
+     */
+    defaultIsCollapsed?: boolean;
+    /** Called with the next collapsed state when the header is toggled. */
+    onCollapsedChange?: (isCollapsed: boolean) => void;
+    /**
+     * Content at the end of the file header, e.g. a "Viewed" checkbox or a menu
+     * of file actions.
+     */
+    headerEnd?: ReactNode;
+    /**
+     * Render content in a full-width row under a line, e.g. review comments.
+     * Return `null` (or `false`) for lines with nothing to show. Called once per line with
+     * its {@link DiffViewerLineRef}; in split view the row sits under the
+     * line's own side.
+     */
+    renderLineAnnotation?: (ref: DiffViewerLineRef) => ReactNode;
+    /**
+     * Makes each line's number a button (e.g. to start a comment on that line).
+     * Receives the line's {@link DiffViewerLineRef}. Only the number on the
+     * line's anchor side is a button, so an unchanged line's original number
+     * stays plain text. Each button is its own Tab stop, like any other set of
+     * independent buttons.
+     */
+    onLineNumberClick?: (ref: DiffViewerLineRef, event: MouseEvent<HTMLButtonElement>) => void;
+    /** Maximum height of the hunk area before it scrolls. */
+    maxHeight?: number | string;
+    /**
+     * Per-instance syntax theme, as on CodeBlock. Without it the nearest
+     * `SyntaxTheme` or the theme's syntax colors apply.
+     */
+    syntaxTheme?: SyntaxThemeDefinition;
+}
+/**
+ * Read-only, syntax-highlighted diff of one file, in unified or split view,
+ * for code review surfaces. Supports review-comment annotation rows under any
+ * line and actionable line numbers.
+ *
+ * @example
+ * ```
+ * const [file] = parseUnifiedDiff(patch);
+ * <DiffViewer file={file} viewMode="split" />
+ * ```
+ */
+export declare function DiffViewer({ ref, file, viewMode, language: languageProp, hasLineNumbers, isWrapped, changeIndicator, inlineHighlight, hasChangeBackground, isCollapsible, isCollapsed: isCollapsedProp, defaultIsCollapsed, onCollapsedChange, headerEnd, renderLineAnnotation, onLineNumberClick, maxHeight, syntaxTheme, xstyle, className, style, ...props }: DiffViewerProps): import("react").JSX.Element;
+export declare namespace DiffViewer {
+    var displayName: string;
+}
+//# sourceMappingURL=DiffViewer.d.ts.map

package/dist/DiffViewer/DiffViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiffViewer.d.ts","sourceRoot":"","sources":["../../src/DiffViewer/DiffViewer.tsx"],"names":[],"mappings":"AAqCA,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,GAAG,EAET,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAalD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,iCAAiC,CAAC;AAqBzC,OAAO,KAAK,EACV,cAAc,EAGd,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAGrB,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjE,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,yCAAyC;IACzC,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1B;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,SAAS,CAAC;IAC7D;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAClB,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC,KACjC,IAAI,CAAC;IACV,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAk0BD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EACzB,GAAG,EACH,IAAI,EACJ,QAAoB,EACpB,QAAQ,EAAE,YAAY,EACtB,cAAqB,EACrB,SAAiB,EACjB,eAA2B,EAC3B,eAAwB,EACxB,mBAA0B,EAC1B,aAAoB,EACpB,WAAW,EAAE,eAAe,EAC5B,kBAA0B,EAC1B,iBAAiB,EACjB,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,eAAe,+BAopBjB;yBA3qBe,UAAU"}