@bridgebrew/ui 0.1.11-next.94 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,54 @@
1
+ import * as React from "react";
2
+ import type { CodeToken } from "../../core/code-block";
3
+ import { type DiffStatus } from "./diff";
4
+ /** One file to show: its own patch (a `git diff` of that file, or its hunks), or where reading it stands. */
5
+ interface DiffViewFile {
6
+ path: string;
7
+ /** Its unified diff; `{ loading: true }` while read; `{ error }` when it could not be; none: not read yet (the caller
8
+ * reads it when `onFileVisible` names it). */
9
+ patch?: string | {
10
+ loading: true;
11
+ } | {
12
+ error: string;
13
+ } | undefined;
14
+ /** Its counts when known before its patch (else the patch's). */
15
+ added?: number | undefined;
16
+ removed?: number | undefined;
17
+ /** A lockfile, a build output: minimized until "Show diff". */
18
+ generated?: boolean | undefined;
19
+ /** Its status when known before its patch (else the patch's). */
20
+ status?: DiffStatus | undefined;
21
+ }
22
+ /** What a ref on DiffView gives. */
23
+ interface DiffViewHandle {
24
+ /** Scrolls the nearest scrolling ancestor to `path`'s file. */
25
+ scrollTo(path: string): void;
26
+ }
27
+ type Tokens = readonly (readonly CodeToken[])[];
28
+ interface DiffViewProps extends Omit<React.ComponentProps<"div">, "children" | "ref"> {
29
+ files: readonly DiffViewFile[];
30
+ /** One column of lines (default), or the old and the new side by side (lines wrap there). */
31
+ mode?: "unified" | "split";
32
+ /** Long lines wrap rather than scroll sideways. */
33
+ wrap?: boolean;
34
+ /** `code` cut into coloured tokens, line by line (Shiki's `codeToTokens(…).tokens`, css-variables theme), for
35
+ * `language` (the file's extension, `ts`, `json`; its name without one); `undefined`: plain. */
36
+ highlight?: (code: string, language: string) => Promise<Tokens | undefined>;
37
+ /** Lines `from` to `to` (1-based, inclusive) of `path`'s new text; fewer at its end. Without it, folds don't expand. */
38
+ loadLines?: (path: string, from: number, to: number) => Promise<readonly string[]>;
39
+ /** A file header's actions (a `⋯` menu), on its right. */
40
+ actions?: (file: DiffViewFile) => React.ReactNode;
41
+ /** Review mode: a Reviewed checkbox in each header; a reviewed file folds. */
42
+ review?: {
43
+ reviewed: ReadonlySet<string>;
44
+ onReviewedChange: (path: string, reviewed: boolean) => void;
45
+ };
46
+ /** A file came into view (or near it): read its patch when it has none. */
47
+ onFileVisible?: (path: string) => void;
48
+ /** The file to scroll to, at once and each time it changes. */
49
+ focus?: string | undefined;
50
+ ref?: React.Ref<DiffViewHandle>;
51
+ }
52
+ declare function DiffView({ files, mode, wrap, highlight, loadLines, actions, review, onFileVisible, focus, ref, className, ...props }: DiffViewProps): React.JSX.Element;
53
+ export { DiffView };
54
+ export type { DiffViewFile, DiffViewHandle, DiffViewProps };
@@ -0,0 +1,65 @@
1
+ /** One line of a hunk. */
2
+ type DiffLine = {
3
+ kind: "context";
4
+ text: string;
5
+ old: number;
6
+ new: number;
7
+ } | {
8
+ kind: "removed";
9
+ text: string;
10
+ old: number;
11
+ } | {
12
+ kind: "added";
13
+ text: string;
14
+ new: number;
15
+ };
16
+ /** One `@@ -oldStart,oldCount +newStart,newCount @@ section` block. */
17
+ interface DiffHunk {
18
+ oldStart: number;
19
+ oldCount: number;
20
+ newStart: number;
21
+ newCount: number;
22
+ /** What git prints after the second `@@`: the enclosing function or heading, often. */
23
+ section: string;
24
+ lines: DiffLine[];
25
+ }
26
+ type DiffStatus = "added" | "deleted" | "renamed" | "modified";
27
+ /** One file of a diff. */
28
+ interface DiffFileModel {
29
+ /** Its path in the repository: the new one, the old one for a deletion. */
30
+ path: string;
31
+ /** Its old path, when it was renamed. */
32
+ oldPath?: string;
33
+ status: DiffStatus;
34
+ hunks: DiffHunk[];
35
+ added: number;
36
+ removed: number;
37
+ }
38
+ /** The unchanged lines between two hunks (or before the first, or after the last: `to` unknown), by their new numbers;
39
+ * a line's old number is its new one plus `offset`. `section`: the next hunk's. */
40
+ interface DiffGap {
41
+ from: number;
42
+ /** The last line of the gap; `undefined`: the end of the file, unknown until read. */
43
+ to: number | undefined;
44
+ offset: number;
45
+ section: string;
46
+ }
47
+ /** A unified git diff, file by file. Text without a `diff --git` line is one file's hunks, named `path`. */
48
+ declare function parseDiff(diff: string, path?: string): DiffFileModel[];
49
+ /** The unchanged lines around `file`'s hunks: before the first, between two, and after the last (its end unknown;
50
+ * none when the last hunk reaches the file's end). None for a file added or deleted whole, nor where two hunks touch. */
51
+ declare function gapsOf(file: Pick<DiffFileModel, "hunks" | "status">): DiffGap[];
52
+ /** A range of characters `[start, end)`. */
53
+ type CharRange = readonly [number, number];
54
+ /** The characters that changed between `before` (a removed line) and `after` (its added counterpart), each side: the
55
+ * words outside their longest common sequence. Nothing when they share less than half their text
56
+ * (two different lines). */
57
+ declare function changedWords(before: string, after: string): [CharRange[], CharRange[]];
58
+ /** A hunk's removed lines paired with the added lines right after them (the first removed with the first added…):
59
+ * the pairs whose words are compared, and the rows of a split view. */
60
+ declare function pairsOf(lines: readonly DiffLine[]): {
61
+ left?: DiffLine;
62
+ right?: DiffLine;
63
+ }[];
64
+ export { changedWords, gapsOf, pairsOf, parseDiff };
65
+ export type { CharRange, DiffFileModel, DiffGap, DiffHunk, DiffLine, DiffStatus };
@@ -0,0 +1,4 @@
1
+ export { DiffView } from "./diff-view";
2
+ export type { DiffViewFile, DiffViewHandle, DiffViewProps } from "./diff-view";
3
+ export { changedWords, gapsOf, pairsOf, parseDiff } from "./diff";
4
+ export type { CharRange, DiffFileModel, DiffGap, DiffHunk, DiffLine, DiffStatus } from "./diff";
@@ -0,0 +1,3 @@
1
+ /** The `--shiki-*` variables a css-variables token names, from the theme's own colours (light, dark and skins follow):
2
+ * tags blue, attributes amber, keywords red, strings green, punctuation grey. */
3
+ export declare const codeTokenPalette: string;
@@ -26,9 +26,12 @@ interface MultiPaneProps extends Omit<React.ComponentProps<"div">, "children"> {
26
26
  /** The panes that scroll their content (the kit's ScrollArea, as a frame's `scrolling`); the others (default) leave
27
27
  * it to their content (a Pane's body, a Detail). */
28
28
  scroll?: PaneName[];
29
+ /** `pane`: the aside a full-height column after a divider (default); `floating`: a card inset from the edges, as tall
30
+ * as its content, scrolling inside it, no divider drawn (the edge still dragged). */
31
+ asideVariant?: "pane" | "floating";
29
32
  /** Its group's props (a customization owner's data attribute). */
30
33
  groupProps?: Omit<React.ComponentProps<typeof ResizablePanelGroup>, "orientation" | "children">;
31
34
  }
32
- declare function MultiPane({ nav, main, aside, mode, collapse, defaultNavSize, defaultAsideSize, storageKey, groupProps, scroll, className, ...props }: MultiPaneProps): React.JSX.Element;
35
+ declare function MultiPane({ nav, main, aside, mode, collapse, defaultNavSize, defaultAsideSize, storageKey, groupProps, scroll, asideVariant, className, ...props }: MultiPaneProps): React.JSX.Element;
33
36
  export { MultiPane, multiPaneNarrowWidth, multiPaneAsideWidth };
34
37
  export type { MultiPaneProps };
@@ -139,6 +139,8 @@ export type { SnoozeMenuProps, SnoozeDialogProps, SnoozePreset, SnoozeChoice, Sn
139
139
  export { BulkBar, BulkAction, BulkSeparator, List, listVariants, ListItem, listItemVariants, ListGroup, } from "./components/composite/list";
140
140
  export type { BulkBarProps, BulkActionProps, ListProps, ListItemProps, SwipeAction, ListGroupProps, } from "./components/composite/list";
141
141
  export * from "./components/composite/command";
142
+ export { DiffView, changedWords, gapsOf, pairsOf, parseDiff, } from "./components/composite/diff-view";
143
+ export type { CharRange, DiffFileModel, DiffGap, DiffHunk, DiffLine, DiffStatus, DiffViewFile, DiffViewHandle, DiffViewProps, } from "./components/composite/diff-view";
142
144
  export { ScreenLink, FollowProvider, useFollow, gestureOf } from "./components/core/screen-link";
143
145
  export { ViewScopeProvider, useEditing, useEditingSignal } from "./lib/view-scope";
144
146
  export type { ViewScope, EditingRegistration } from "./lib/view-scope";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bridgebrew/ui",
3
- "version": "0.1.11-next.94",
3
+ "version": "0.1.11",
4
4
  "description": "Bridge UI: the toolkit Bridge and its plugins draw with (served to every page as @bridge/ui).",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,65 @@
1
+ name: DiffView
2
+ description: "A git diff to read, file by file: a sticky header per file (icon, name, folder, +/−, actions), its hunks unified (one number column, the new number, − on a removed line, a coloured gutter bar) or split, the words that changed inside a removed/added pair marked, coloured through the caller's highlighter, the unchanged lines between hunks folded (expandable by 20 or all with loadLines), generated files minimized, an optional review mode."
3
+ layer: composite
4
+ category: data-display
5
+ when_to_use:
6
+ - "Changes to review or commit: a session's uncommitted files, a branch, a pull request"
7
+ - "Many files read one by one: give each file without its patch, read it when onFileVisible names it"
8
+ when_not_to_use:
9
+ - "Code to read and copy, with no change — use CodeBlock"
10
+ - "A file's counts only, in a list or a tree — draw its +/− beside its name"
11
+ props:
12
+ - name: files
13
+ type: "{ path: string; patch?: string | { loading: true } | { error: string }; added?: number; removed?: number; generated?: boolean; status?: 'added' | 'deleted' | 'renamed' | 'modified' }[]"
14
+ required: true
15
+ description: "Each file's own unified diff (its `diff --git` chunk, or hunks alone); none: not read yet. The kit parses it (parseDiff: files → hunks → lines with their old and new numbers and kind)"
16
+ - name: mode
17
+ type: "'unified' | 'split'"
18
+ required: false
19
+ description: "One column of lines (default), or old and new side by side (lines wrap there)"
20
+ - name: wrap
21
+ type: boolean
22
+ required: false
23
+ description: "Long lines wrap rather than scroll sideways"
24
+ - name: highlight
25
+ type: "(code: string, language: string) => Promise<CodeToken[][] | undefined>"
26
+ required: false
27
+ description: "Syntax colours, as CodeBlock's tokens (Shiki's codeToTokens with its css-variables theme, in the caller's bundle); language is the file's extension. Each side (old, new) highlighted as one text. Plain without it"
28
+ - name: loadLines
29
+ type: "(path: string, from: number, to: number) => Promise<string[]>"
30
+ required: false
31
+ description: "Lines from–to (1-based, inclusive) of the file's new text, fewer at its end: the folds' arrows read them. Without it, folds only say how many lines they hide"
32
+ - name: actions
33
+ type: "(file) => ReactNode"
34
+ required: false
35
+ description: "A file header's actions, on its right (a ⋯ menu)"
36
+ - name: review
37
+ type: "{ reviewed: ReadonlySet<string>; onReviewedChange: (path, reviewed) => void }"
38
+ required: false
39
+ description: "Review mode: a Reviewed checkbox in each header; a reviewed file folds to its header"
40
+ - name: onFileVisible
41
+ type: "(path: string) => void"
42
+ required: false
43
+ description: "A file came into view or near it (IntersectionObserver): read its patch then"
44
+ - name: focus
45
+ type: string
46
+ required: false
47
+ description: "The file to scroll to, at once and on each change; a ref's scrollTo(path) does the same on demand"
48
+ composition_partners:
49
+ - Dialog (fullscreen, a list of files beside it)
50
+ - DropdownMenu (a file's ⋯ actions)
51
+ examples:
52
+ - title: "One file, unified"
53
+ code: |
54
+ <DiffView files={[{ path: "src/format.js", patch }]} />
55
+ - title: "Many files read as they show, with colours and expandable folds"
56
+ code: |
57
+ <DiffView
58
+ files={paths.map((path) => ({ path, patch: patches.get(path) }))}
59
+ onFileVisible={read}
60
+ highlight={tokensOf}
61
+ loadLines={(path, from, to) => linesOf(path, from, to)}
62
+ focus={picked}
63
+ />
64
+ accessibility_notes: "Each file is a region named by its path. The fold arrows are buttons named Show 20 lines above / below and Show N unchanged lines. A removed line's number reads −."
65
+ notes: "Sub-parts by data-slot: diff-view (data-mode), diff-view-header, diff-view-body, diff-view-line (data-kind context | added | removed), diff-view-number, diff-view-fold, diff-view-counts; a changed word is a span with data-changed. The parse is exported (parseDiff, gapsOf, pairsOf, changedWords) for counts and paths without drawing."