@astryx-vue/lab 0.1.1 → 0.2.0

package/README.md

@@ -24,6 +24,7 @@ Or pick single files: `@astryx-vue/lab/styles/stat.css`, `.../log-stream.css`, a
 | --- | --- |
 | `Stat` | KPI/metric display: label, big tabular value, optional sentiment-aware delta, description, trend slot. |
 | `CircularProgress` | Ring-shaped progress indicator, determinate or indeterminate. |
+| `DiffViewer` | Read-only unified or split diff for one file, with inline highlighting. |
 | `InfoTip` | Small "i" button that reveals a tooltip on hover, keyboard focus, and tap. |
 | `SVGIcon` | CSS-variable-driven SVG icon with variations (linear, bold, twotone, bulk, broken), path roles, and mask-based gaps. |
 | `LogStream` | Streaming log viewer with level accents, expandable detail rows, follow-scroll tailing, and a terminal variant. |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { VNodeChild } from "vue";
-import { FieldStatusInput, IconSize, PopoverPlacement } from "@astryx-vue/core";
+import { FieldStatusInput, IconSize, PopoverPlacement, SyntaxThemeDefinition } from "@astryx-vue/core";
 //#region src/CircularProgress/types.d.ts
 /** Variants a theme can extend through declaration merging in TypeScript. */
 interface CircularProgressVariantMap {
@@ -63,28 +63,291 @@ interface CircularProgressProps {
 //#endregion
 //#region src/CircularProgress/CircularProgress.vue.d.ts
 declare var __VLS_1$1: {};
-type __VLS_Slots$3 = {} & {
+type __VLS_Slots$4 = {} & {
   default?: (props: typeof __VLS_1$1) => any;
 };
-declare const __VLS_base$3: import("vue").DefineComponent<CircularProgressProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<CircularProgressProps> & Readonly<{}>, {
+declare const __VLS_base$4: import("vue").DefineComponent<CircularProgressProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<CircularProgressProps> & Readonly<{}>, {
   value: number;
-  size: CircularProgressSize;
   max: number;
   isLabelHidden: boolean;
   hasValueLabel: boolean;
   formatValueLabel: (value: number, max: number) => string;
+  size: CircularProgressSize;
   variant: keyof CircularProgressVariantMap;
   isIndeterminate: boolean;
   isDisabled: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$9: __VLS_WithSlots$4<typeof __VLS_base$4, __VLS_Slots$4>;
+declare const _default: typeof __VLS_export$9;
+type __VLS_WithSlots$4<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/DiffViewer/diffTypes.d.ts
+/**
+ * @file diffTypes.ts
+ * @input None (type-only module)
+ * @output DiffViewerFile, DiffViewerHunk, DiffViewerLine, DiffViewerLineKind,
+ *   DiffViewerFileStatus, DiffViewerSide, DiffViewerLineRef
+ * @position Lab diff model; produced by parseUnifiedDiff / createDiffFile and
+ *   consumed by DiffViewer
+ *
+ * 数据模型和上游 `@astryxdesign/lab` 的 DiffViewer 保持一致：一个 hunk 里的行
+ * 去掉开头 `+`/`-`/空格标记后，各自记录旧文件和新文件里的行号。
+ */
+/** One line of a hunk: adds, removes, or keeps a line. */
+type DiffViewerLineKind = 'added' | 'removed' | 'context';
+/** How the file changed as a whole. */
+type DiffViewerFileStatus = 'added' | 'deleted' | 'modified' | 'renamed';
+/**
+ * Which version of the file a line number belongs to: `old` is the original
+ * (left in split view), `new` the changed version (right in split view).
+ */
+type DiffViewerSide = 'old' | 'new';
+/** One line of a hunk, without its leading `+`/`-`/space glyph. */
+interface DiffViewerLine {
+  kind: DiffViewerLineKind;
+  /** The line's text with the diff glyph removed. */
+  content: string;
+  /** 1-based line number in the old file; `null` for an added line. */
+  oldLineNumber: number | null;
+  /** 1-based line number in the new file; `null` for a removed line. */
+  newLineNumber: number | null;
+}
+/** One `@@` hunk: a run of changed lines with their surrounding context. */
+interface DiffViewerHunk {
+  /** The hunk header as written, e.g. `@@ -12,7 +12,9 @@ function save()`. */
+  header: string;
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: DiffViewerLine[];
+}
+/** One file's changes. */
+interface DiffViewerFile {
+  /** Path before the change; `null` when the file was added. */
+  oldPath: string | null;
+  /** Path after the change; `null` when the file was deleted. */
+  newPath: string | null;
+  status: DiffViewerFileStatus;
+  /** True when the patch reports a binary change with no line hunks. */
+  isBinary: boolean;
+  hunks: DiffViewerHunk[];
+}
+/**
+ * Identifies one rendered line for annotations and line-number clicks. Every
+ * line has exactly one ref, the same in unified and split view, so `side` +
+ * `lineNumber` is a stable anchor: an added line is `new`, a removed line is
+ * `old`, and a context line is `new`.
+ */
+interface DiffViewerLineRef {
+  side: DiffViewerSide;
+  lineNumber: number;
+  line: DiffViewerLine;
+  hunkIndex: number;
+}
+//#endregion
+//#region src/DiffViewer/createDiffFile.d.ts
+interface CreateDiffFileOptions {
+  /** The original text. */
+  oldValue: string;
+  /** The changed text. */
+  newValue: string;
+  /**
+   * Path of the file on both sides. `oldPath` / `newPath` take precedence
+   * when they are given.
+   */
+  path?: string;
+  /** Path before the change; pass `null` to mark the file as added. */
+  oldPath?: string | null;
+  /** Path after the change; pass `null` to mark the file as deleted. */
+  newPath?: string | null;
+  /**
+   * Unchanged lines kept around each change. Changes closer together than
+   * twice this share one hunk. `NaN` falls back to the default.
+   * @default 3
+   */
+  contextLines?: number;
+}
+/**
+ * Compute a {@link DiffViewerFile} from two versions of a text, for callers
+ * that hold file contents rather than a patch.
+ *
+ * @example
+ * ```
+ * const file = createDiffFile({oldValue: before, newValue: after, path: 'src/app.ts'});
+ * <DiffViewer file={file} />
+ * ```
+ */
+export declare function createDiffFile({ oldValue, newValue, path, oldPath: oldPathOption, newPath: newPathOption, contextLines }: CreateDiffFileOptions): DiffViewerFile;
+//#endregion
+//#region src/DiffViewer/types.d.ts
+/** How hunks are laid out: one column, or old and new side by side. */
+type DiffViewerViewMode = 'unified' | 'split';
+/**
+ * How finely to highlight what changed inside a removed line and the added
+ * line that replaced it: by `word`, by `char`acter, or `none`.
+ */
+type DiffViewerInlineHighlight = 'word' | 'char' | 'none';
+interface DiffViewerProps {
+  /**
+   * 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.
+   * @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.
+   * @default false
+   */
+  isWrapped?: boolean;
+  /**
+   * 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;
+  /**
+   * 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 `collapsedChange`. */
+  isCollapsed?: boolean;
+  /**
+   * Initial collapsed state when uncontrolled.
+   * @default false
+   */
+  defaultIsCollapsed?: boolean;
+  /** Maximum height of the hunk area before it scrolls. */
+  maxHeight?: number | string;
+  /**
+   * Per-instance syntax theme. Without it the nearest `SyntaxTheme` or the
+   * theme's syntax colors apply.
+   */
+  syntaxTheme?: SyntaxThemeDefinition;
+  /** Accessible name for the scrollable hunk area. @default 'Diff' */
+  label?: string;
+  /**
+   * Render content in a full-width row under a line, e.g. review comments.
+   * Return `null` for lines with nothing to show. In split view the row sits
+   * under the line's own side.
+   */
+  renderLineAnnotation?: (ref: DiffViewerLineRef) => VNodeChild;
+}
+interface DiffViewerEmits {
+  /** The header disclosure was toggled; carries the next collapsed state. */
+  'collapsedChange': [isCollapsed: boolean];
+  /** v-model:isCollapsed support. */
+  'update:isCollapsed': [isCollapsed: boolean];
+  /**
+   * A line number was clicked. Only the number on the line's anchor side is a
+   * button, so a context line reports its new side.
+   */
+  'lineNumberClick': [ref: DiffViewerLineRef, event: MouseEvent];
+}
+interface DiffViewerSlots {
+  /** Content at the end of the file header, e.g. a "Viewed" checkbox. */
+  headerEnd?: () => VNodeChild;
+}
+//#endregion
+//#region src/DiffViewer/DiffViewer.vue.d.ts
+type __VLS_Slots$3 = DiffViewerSlots;
+declare const __VLS_base$3: import("vue").DefineComponent<DiffViewerProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+  collapsedChange: (isCollapsed: boolean) => any;
+  "update:isCollapsed": (isCollapsed: boolean) => any;
+  lineNumberClick: (ref: DiffViewerLineRef, event: MouseEvent) => any;
+}, string, import("vue").PublicProps, Readonly<DiffViewerProps> & Readonly<{
+  onCollapsedChange?: ((isCollapsed: boolean) => any) | undefined;
+  "onUpdate:isCollapsed"?: ((isCollapsed: boolean) => any) | undefined;
+  onLineNumberClick?: ((ref: DiffViewerLineRef, event: MouseEvent) => any) | undefined;
+}>, {
+  label: string;
+  maxHeight: string | number;
+  viewMode: DiffViewerViewMode;
+  language: string;
+  hasLineNumbers: boolean;
+  isWrapped: boolean;
+  inlineHighlight: DiffViewerInlineHighlight;
+  isCollapsible: boolean;
+  isCollapsed: boolean;
+  defaultIsCollapsed: boolean;
+  syntaxTheme: import("@astryx-vue/core").SyntaxThemeDefinition;
+  renderLineAnnotation: (ref: DiffViewerLineRef) => import("vue").VNodeChild;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$8: __VLS_WithSlots$3<typeof __VLS_base$3, __VLS_Slots$3>;
-declare const _default: typeof __VLS_export$8;
+declare const _default$1: typeof __VLS_export$8;
 type __VLS_WithSlots$3<T, S> = T & {
   new (): {
     $slots: S;
   };
 };
 //#endregion
+//#region src/DiffViewer/inlineDiff.d.ts
+/**
+ * @file inlineDiff.ts
+ * @input Two lines of text: a removed line and the added line that replaced it
+ * @output Exports diffInlineRanges and InlineRange: the changed character
+ *   ranges on each side, for word- or character-level highlighting
+ * @position Lab helper used by DiffViewer's inline change highlighting
+ *
+ * Finds the longest common subsequence of the two lines' tokens (words,
+ * whitespace runs and single punctuation characters, or single characters)
+ * and reports what falls outside it on each side. Pure and synchronous.
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/DiffViewer/inlineDiff.test.ts
+ * - /packages/lab/src/DiffViewer/DiffViewer.tsx (the caller)
+ */
+/** Half-open `[start, end)` character range within one line. */
+type InlineRange = readonly [start: number, end: number];
+/** How finely to compare a pair of lines. */
+type InlineDiffGranularity = 'word' | 'char';
+interface InlineDiffResult {
+  /** Changed ranges in the removed (old) line. */
+  old: InlineRange[];
+  /** Changed ranges in the added (new) line. */
+  new: InlineRange[];
+}
+//#endregion
+//#region src/DiffViewer/parseUnifiedDiff.d.ts
+/**
+ * Parse a unified diff into one {@link DiffViewerFile} per file.
+ *
+ * Accepts `git diff` output (with `diff --git`, mode, rename, copy, and
+ * binary lines), classic `diff -u` output (`---`/`+++` pairs), several files in one
+ * patch, and a bare `@@` hunk with no file header (returned as one file with
+ * null paths). Input it cannot read yields `[]`; it never throws.
+ *
+ * @example
+ * ```
+ * const files = parseUnifiedDiff(patch);
+ * files.map((file) => <DiffViewer key={file.newPath ?? file.oldPath} file={file} />);
+ * ```
+ */
+export declare function parseUnifiedDiff(patch: string): DiffViewerFile[];
+//#endregion
 //#region src/InfoTip/types.d.ts
 /**
  * Size of the info icon. Maps 1:1 to core `Icon` sizes
@@ -119,7 +382,7 @@ declare const __VLS_base$2: import("vue").DefineComponent<InfoTipProps, {}, {},
   content: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$7: __VLS_WithSlots$2<typeof __VLS_base$2, __VLS_Slots$2>;
-declare const _default$1: typeof __VLS_export$7;
+declare const _default$2: typeof __VLS_export$7;
 type __VLS_WithSlots$2<T, S> = T & {
   new (): {
     $slots: S;
@@ -249,7 +512,7 @@ declare const __VLS_export$6: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_
 }>) => import("vue").VNode & {
   __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
-declare const _default$2: typeof __VLS_export$6;
+declare const _default$3: typeof __VLS_export$6;
 type __VLS_PrettifyLocal$3<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
 //#endregion
 //#region src/LogStream/types.d.ts
@@ -335,7 +598,7 @@ declare const __VLS_base$1: import("vue").DefineComponent<__VLS_PublicProps, {},
   hasTimestamps: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$5: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
-declare const _default$3: typeof __VLS_export$5;
+declare const _default$4: typeof __VLS_export$5;
 type __VLS_WithSlots$1<T, S> = T & {
   new (): {
     $slots: S;
@@ -426,7 +689,7 @@ declare const __VLS_export$4: <T extends SearchableItem>(__VLS_props: NonNullabl
 }>) => import("vue").VNode & {
   __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
-declare const _default$4: typeof __VLS_export$4;
+declare const _default$5: typeof __VLS_export$4;
 type __VLS_PrettifyLocal$2<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
 //#endregion
 //#region src/Stat/types.d.ts
@@ -473,12 +736,12 @@ type __VLS_Slots = {} & {
 };
 declare const __VLS_base: import("vue").DefineComponent<StatProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<StatProps> & Readonly<{}>, {
   value: string;
+  size: StatSize;
   delta: StatDelta;
   description: string;
-  size: StatSize;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$3: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
-declare const _default$6: typeof __VLS_export$3;
+declare const _default$7: typeof __VLS_export$3;
 type __VLS_WithSlots<T, S> = T & {
   new (): {
     $slots: S;
@@ -626,7 +889,7 @@ declare const __VLS_export$2: import("vue").DefineComponent<SVGIconProps, {}, {}
   variation: SVGIconVariation;
   color: SVGIconColor;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default$5: typeof __VLS_export$2;
+declare const _default$6: typeof __VLS_export$2;
 //#endregion
 //#region src/SVGIcon/types-xif.d.ts
 /**
@@ -850,7 +1113,7 @@ declare const __VLS_export$1: <T extends string>(__VLS_props: NonNullable<Awaite
 }>) => import("vue").VNode & {
   __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
-declare const _default$7: typeof __VLS_export$1;
+declare const _default$8: typeof __VLS_export$1;
 type __VLS_PrettifyLocal$1<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
 //#endregion
 //#region src/TransferList/TransferListSelector.vue.d.ts
@@ -906,7 +1169,7 @@ declare const __VLS_export: <T extends string>(__VLS_props: NonNullable<Awaited<
 }>) => import("vue").VNode & {
   __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
-declare const _default$8: typeof __VLS_export;
+declare const _default$9: typeof __VLS_export;
 type __VLS_PrettifyLocal<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
 //#endregion
-export { _default as CircularProgress, type CircularProgressProps, type CircularProgressSize, type CircularProgressVariant, type CircularProgressVariantMap, type IconShape, type IconShapeRole, _default$1 as InfoTip, type InfoTipProps, type InfoTipSize, _default$2 as ListInput, type ListInputChange, type ListInputColumn, type ListInputColumnWidth, type ListInputEmits, type ListInputProps, type ListInputRenderContext, type ListInputValueContext, type LogEntry, _default$3 as LogStream, type LogStreamEmits, type LogStreamLevel, type LogStreamProps, _default$4 as MobileTokenizer, type MobileTokenizerChange, type MobileTokenizerEmits, type MobileTokenizerProps, type PanelGroup, type PanelRow, type PathPersonality, _default$5 as SVGIcon, type SVGIconColor, type SVGIconDef, type SVGIconProps, type SVGIconSize, type SVGIconVariation, type SearchSource, type SearchableItem, _default$6 as Stat, type StatDelta, type StatDeltaDirection, type StatDeltaSentiment, type StatProps, type StatSize, _default$7 as TransferList, type TransferListEmits, type TransferListOption, type TransferListProps, _default$8 as TransferListSelector, type TransferListSlots, type XIFAnimate, type XIFIcon, type XIFPath, type XIFPersonality, type XIFSlot };
+export { _default as CircularProgress, type CircularProgressProps, type CircularProgressSize, type CircularProgressVariant, type CircularProgressVariantMap, type CreateDiffFileOptions, _default$1 as DiffViewer, type DiffViewerEmits, type DiffViewerFile, type DiffViewerFileStatus, type DiffViewerHunk, type DiffViewerInlineHighlight, type DiffViewerLine, type DiffViewerLineKind, type DiffViewerLineRef, type DiffViewerProps, type DiffViewerSide, type DiffViewerSlots, type DiffViewerViewMode, type IconShape, type IconShapeRole, _default$2 as InfoTip, type InfoTipProps, type InfoTipSize, type InlineDiffGranularity, type InlineDiffResult, type InlineRange, _default$3 as ListInput, type ListInputChange, type ListInputColumn, type ListInputColumnWidth, type ListInputEmits, type ListInputProps, type ListInputRenderContext, type ListInputValueContext, type LogEntry, _default$4 as LogStream, type LogStreamEmits, type LogStreamLevel, type LogStreamProps, _default$5 as MobileTokenizer, type MobileTokenizerChange, type MobileTokenizerEmits, type MobileTokenizerProps, type PanelGroup, type PanelRow, type PathPersonality, _default$6 as SVGIcon, type SVGIconColor, type SVGIconDef, type SVGIconProps, type SVGIconSize, type SVGIconVariation, type SearchSource, type SearchableItem, _default$7 as Stat, type StatDelta, type StatDeltaDirection, type StatDeltaSentiment, type StatProps, type StatSize, _default$8 as TransferList, type TransferListEmits, type TransferListOption, type TransferListProps, _default$9 as TransferListSelector, type TransferListSlots, type XIFAnimate, type XIFIcon, type XIFPath, type XIFPersonality, type XIFSlot };