Skip to content

Commit d23d0e7

Browse files
TomPlumTomPlum
authored
Custom HTML Graph Tooltip Prop (#106)
2 parents cddd3c7 + 7eca164 commit d23d0e7

File tree

11 files changed

+468
-197
lines changed

11 files changed

+468
-197
lines changed

‎README.md‎

Lines changed: 131 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -30,20 +30,21 @@ A flexible and interactive React component for visualising Git commit history. D
3030
* [GitLogPaged](#gitlogpaged)
3131
* [Optional](#optional)
3232
* [GitLog](#gitlog-1)
33-
* [GitLogPaged](#gitlogpaged-1)
34-
* [GitLogStylingProps](#gitlogstylingprops)
3533
* [GitLogPaging](#gitlogpaging)
36-
* [GitLogIndexStatus](#gitlogindexstatus)
37-
* [GitLogUrlBuilder](#gitlogurlbuilder)
38-
* [CommitFilter](#commitfilter)
34+
* [GitLogPaged](#gitlogpaged-1)
3935
* [GraphHTMLGrid](#graphhtmlgrid)
36+
* [CustomCommitNode](#customcommitnode)
4037
* [GraphCanvas2D](#graphcanvas2d)
41-
* [NodeTheme](#nodetheme)
4238
* [Table](#table)
4339
* [GitLogTableStylingProps](#gitlogtablestylingprops)
4440
* [CustomTableRow](#customtablerow)
45-
* [CustomCommitNode](#customcommitnode)
46-
* [BreakPointTheme](#breakpointtheme)
41+
* [Common Types](#common-types)
42+
* [GitLogStylingProps](#gitlogstylingprops)
43+
* [GitLogIndexStatus](#gitlogindexstatus)
44+
* [GitLogUrlBuilder](#gitlogurlbuilder)
45+
* [CommitFilter](#commitfilter)
46+
* [NodeTheme](#nodetheme)
47+
* [BreakPointTheme](#breakpointtheme)
4748
* [Development](#development)
4849
* [References](#references)
4950
* [Roadmap](#roadmap)
@@ -303,6 +304,13 @@ All components have optional props to further configure the log.
303304
| `showGitIndex` | `boolean` | Enables the Git index "pseudo-commit' entry above the HEAD commit. |
304305
| `filter` | [`CommitFilter<T>`](#commitfilter) | Filters the commits in the log based on the response from the function. |
305306

307+
#### GitLogPaging
308+
309+
| Prop | Type | Description |
310+
|--------|----------|-------------------------------------------------|
311+
| `size` | `number` | The number of rows to show per page. |
312+
| `page` | `number` | The page number to display (first page is `0`). |
313+
306314
### GitLogPaged
307315

308316
| Property | Type | Description |
@@ -322,52 +330,6 @@ All components have optional props to further configure the log.
322330
| `showGitIndex` | `boolean` | Enables the Git index "pseudo-commit' entry above the HEAD commit. |
323331
| `filter` | [`CommitFilter<T>`](#commitfilter) | Filters the commits in the log based on the response from the function. |
324332

325-
326-
#### GitLogStylingProps
327-
| Property | Type | Description |
328-
|-------------------|-----------------|--------------------------------------------------------------------------------|
329-
| `containerClass` | `string` | Class name for the wrapping `<div>` containing branches, graph, and log table. |
330-
| `containerStyles` | `CSSProperties` | React CSS styling object for the wrapping container `<div>`. |
331-
332-
#### GitLogPaging
333-
334-
| Prop | Type | Description |
335-
|--------|----------|-------------------------------------------------|
336-
| `size` | `number` | The number of rows to show per page. |
337-
| `page` | `number` | The page number to display (first page is `0`). |
338-
339-
#### GitLogIndexStatus
340-
341-
| Prop | Type | Description |
342-
|------------|----------|---------------------------------------------------------------------------|
343-
| `added` | `number` | The number of added files in the git index for the checked-out branch. |
344-
| `deleted` | `number` | The number of deleted files in the git index for the checked-out branch. |
345-
| `modified` | `number` | The number of modified files in the git index for the checked-out branch. |
346-
347-
#### GitLogUrlBuilder
348-
349-
A function with the following signature
350-
```typescript
351-
type GitLogUrlBuilder = (args: GitLogUrlBuilderArgs) => GitLogUrls
352-
```
353-
Returns an object of type `GitLogUrls` with the following fields.
354-
355-
| Prop | Type | Description |
356-
|------------|----------|------------------------------------------------------------------------------------------|
357-
| `commit` | `string` | A resolved URL to a particular commit hash on the external Git providers remote website. |
358-
| `branch` | `string` | A resolved URL to a branch on the external Git providers remote website. |
359-
360-
#### CommitFilter
361-
362-
A function with the following signature
363-
```typescript
364-
type CommitFilter<T> = (commits: Commit<T>[]) => Commit<T>[]
365-
```
366-
367-
Is passed the array of `Commit<T>` objects from the log based on the current pagination configuration and must return the filtered array based on your own domain-specific behaviour.
368-
369-
The logs' subcomponents will respond accordingly based on the filtered list of commits.
370-
371333
### GraphHTMLGrid
372334

373335
| Property | Type | Description |
@@ -381,6 +343,80 @@ The logs' subcomponents will respond accordingly based on the filtered list of c
381343
| `highlightedBackgroundHeight` | `number` | The height, in pixels, of the background colour of a row that is being previewed or has been selected. |
382344
| `node` | [`CustomCommitNode`](#customcommitnode) | A function that returns a custom commit node implementation used by the graph. |
383345
| `breakPointTheme` | [`BreakPointTheme`](#breakpointtheme) | Changes how the break-points between rows render when the log is being filtered. |
346+
| `tooltip` | [`CustomTooltip`](#customtooltip) | Overrides the graph node tooltip with a custom implementation. Commit metadata is injected. |
347+
348+
#### CustomCommitNode
349+
350+
A function with the following signature:
351+
```typescript
352+
type CustomCommitNode = (props: CustomCommitNodeProps) => ReactElement
353+
```
354+
355+
For example:
356+
```typescript jsx
357+
<GitLog.GraphHTMLGrid
358+
nodeSize={25}
359+
node={({ nodeSize, colour, isIndexPseudoNode, rowIndex }) => (
360+
<div
361+
className={styles.Node}
362+
style={{
363+
width: nodeSize,
364+
height: nodeSize,
365+
background: `url('https://placecats.com/${images[rowIndex % images.length]}/50/50?fit=contain&position=top') 50% 50%`,
366+
border: `2px ${isIndexPseudoNode ? 'dotted' : 'solid'} ${colour}`
367+
}}
368+
/>
369+
)}
370+
/>
371+
```
372+
373+
The following properties are injected into the functions `props` argument:
374+
375+
| Property | Type | Description |
376+
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|
377+
| `commit` | `Commit` | Details of the commit that the node is being rendered for. |
378+
| `colour` | `string` | The colour of the commit based on the column in its and the theme. |
379+
| `rowIndex` | `number` | The (zero-based) index of the row that the node is in. |
380+
| `columnIndex` | `number` | The (zero-based) index of the column that the node is in. |
381+
| `nodeSize` | `number` | The diameter (in pixels) of the node. This defaults but can be changed in the graph props. |
382+
| `isIndexPseudoNode` | `boolean` | Denotes whether the node is the "pseudo node" added above the head to represent the working tree index. |
383+
384+
#### CustomTooltip
385+
386+
A function with the following signature:
387+
```typescript
388+
type CustomTooltip = (props: CustomTooltipProps) => ReactElement<HTMLElement>
389+
```
390+
391+
For example:
392+
```typescript jsx
393+
<GitLog.GraphHTMLGrid
394+
showCommitNodeTooltips
395+
tooltip={({ commit, backgroundColour, borderColour }) => (
396+
<div
397+
data-testid='my-custom-tooltip'
398+
style={{
399+
border: `2px solid ${borderColour}`,
400+
backgroundColor: backgroundColour,
401+
color: 'white',
402+
padding: '20px 10px',
403+
borderRadius: '5px'
404+
}}
405+
>
406+
<p>My Custom Tooltip</p>
407+
<p>{commit.message}</p>
408+
</div>
409+
)}
410+
/>
411+
```
412+
413+
The following properties are injected into the functions `props` argument:
414+
415+
| Property | Type | Description |
416+
|--------------------|----------|-------------------------------------------------------------------------------|
417+
| `commit` | `Commit` | Details of the commit that the tooltip is being rendered for. |
418+
| `borderColour` | `string` | The border colour of the commit based on the column in its and the theme. |
419+
| `backgroundColour` | `number` | The background colour of the commit based on the column in its and the theme. |
384420
385421
### GraphCanvas2D
386422
@@ -392,13 +428,6 @@ The logs' subcomponents will respond accordingly based on the filtered list of c
392428
| `enableResize` | `boolean` | Enables horizontal resizing of the graph. Default: `false`. |
393429
| `breakPointTheme` | [`BreakPointTheme`](#breakpointtheme) | Changes how the break-points between rows render when the log is being filtered. |
394430
395-
#### NodeTheme
396-
397-
| Prop | Type | Description |
398-
|-----------|----------|-----------------------------------------------------------------------|
399-
| `default` | `string` | The default theme where nodes change their style based on their type. |
400-
| `plain` | `string` | All nodes look the same, except for their colours. |
401-
402431
### Table
403432
404433
| Property | Type | Description |
@@ -460,43 +489,55 @@ The following properties are injected into the functions `props` argument:
460489
| `previewed` | `boolean` | Whether the row is previewed (is being hovered over). |
461490
| `backgroundColour` | `string` | The colour of the background as is normally applied to the table row. |
462491
463-
#### CustomCommitNode
492+
## Common Types
464493
465-
A function with the following signature:
494+
### GitLogStylingProps
495+
| Property | Type | Description |
496+
|-------------------|-----------------|--------------------------------------------------------------------------------|
497+
| `containerClass` | `string` | Class name for the wrapping `<div>` containing branches, graph, and log table. |
498+
| `containerStyles` | `CSSProperties` | React CSS styling object for the wrapping container `<div>`. |
499+
500+
501+
### GitLogIndexStatus
502+
503+
| Prop | Type | Description |
504+
|------------|----------|---------------------------------------------------------------------------|
505+
| `added` | `number` | The number of added files in the git index for the checked-out branch. |
506+
| `deleted` | `number` | The number of deleted files in the git index for the checked-out branch. |
507+
| `modified` | `number` | The number of modified files in the git index for the checked-out branch. |
508+
509+
### GitLogUrlBuilder
510+
511+
A function with the following signature
466512
```typescript
467-
type CustomCommitNode = (props: CustomCommitNodeProps) => ReactElement
513+
type GitLogUrlBuilder = (args: GitLogUrlBuilderArgs) => GitLogUrls
468514
```
515+
Returns an object of type `GitLogUrls` with the following fields.
469516
470-
For example:
471-
```typescript jsx
472-
<GitLog.GraphHTMLGrid
473-
nodeSize={25}
474-
node={({ nodeSize, colour, isIndexPseudoNode, rowIndex }) => (
475-
<div
476-
className={styles.Node}
477-
style={{
478-
width: nodeSize,
479-
height: nodeSize,
480-
background: `url('https://placecats.com/${images[rowIndex % images.length]}/50/50?fit=contain&position=top') 50% 50%`,
481-
border: `2px ${isIndexPseudoNode ? 'dotted' : 'solid'} ${colour}`
482-
}}
483-
/>
484-
)}
485-
/>
517+
| Prop | Type | Description |
518+
|------------|----------|------------------------------------------------------------------------------------------|
519+
| `commit` | `string` | A resolved URL to a particular commit hash on the external Git providers remote website. |
520+
| `branch` | `string` | A resolved URL to a branch on the external Git providers remote website. |
521+
522+
### CommitFilter
523+
524+
A function with the following signature
525+
```typescript
526+
type CommitFilter<T> = (commits: Commit<T>[]) => Commit<T>[]
486527
```
487528
488-
The following properties are injected into the functions `props` argument:
529+
Is passed the array of `Commit<T>` objects from the log based on the current pagination configuration and must return the filtered array based on your own domain-specific behaviour.
489530
490-
| Property | Type | Description |
491-
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|
492-
| `commit` | `Commit` | Details of the commit that the node is being rendered for. |
493-
| `colour` | `string` | The colour of the commit based on the column in its and the theme. |
494-
| `rowIndex` | `number` | The (zero-based) index of the row that the node is in. |
495-
| `columnIndex` | `number` | The (zero-based) index of the column that the node is in. |
496-
| `nodeSize` | `number` | The diameter (in pixels) of the node. This defaults but can be changed in the graph props. |
497-
| `isIndexPseudoNode` | `boolean` | Denotes whether the node is the "pseudo node" added above the head to represent the working tree index. |
531+
The logs' subcomponents will respond accordingly based on the filtered list of commits.
532+
533+
### NodeTheme
534+
535+
| Prop | Type | Description |
536+
|-----------|----------|-----------------------------------------------------------------------|
537+
| `default` | `string` | The default theme where nodes change their style based on their type. |
538+
| `plain` | `string` | All nodes look the same, except for their colours. |
498539
499-
#### BreakPointTheme
540+
### BreakPointTheme
500541
501542
The following themes are available:
502543

‎package-lock.json‎

Lines changed: 4 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/demo/src/GitLog.stories.tsx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,82 @@ export const CustomCommitNode = () => {
483483
)}
484484
/>
485485

486+
<GitLog.Table
487+
className={styles.table}
488+
/>
489+
</GitLog>
490+
)}
491+
</div>
492+
)
493+
}
494+
495+
export const CustomCommitTooltip = () => {
496+
const {
497+
loading,
498+
colours,
499+
entries,
500+
branch,
501+
buildUrls,
502+
repository,
503+
backgroundColour,
504+
handleChangeColors,
505+
handleChangeRepository
506+
} = useStoryState()
507+
508+
const { theme } = useDemoContext()
509+
510+
return (
511+
<div style={{ background: backgroundColour }} className={styles.container}>
512+
<StoryHeader
513+
colours={colours}
514+
repository={repository}
515+
onChangeColours={handleChangeColors}
516+
onChangeRepository={handleChangeRepository}
517+
/>
518+
519+
{loading && (
520+
<div className={styles.loading}>
521+
<Loading />
522+
</div>
523+
)}
524+
525+
{!loading && entries && (
526+
<GitLog
527+
colours={colours.colors}
528+
entries={entries}
529+
theme={theme}
530+
currentBranch={branch}
531+
classes={{
532+
containerStyles: {
533+
background: backgroundColour
534+
},
535+
containerClass: styles.gitLogContainer
536+
}}
537+
indexStatus={{
538+
added: 2,
539+
modified: 5,
540+
deleted: 1
541+
}}
542+
urls={buildUrls}
543+
>
544+
<GitLog.GraphHTMLGrid
545+
showCommitNodeTooltips
546+
tooltip={({ commit, backgroundColour, borderColour }) => (
547+
<div
548+
style={{
549+
border: `2px solid ${borderColour}`,
550+
backgroundColor: backgroundColour,
551+
color: 'white',
552+
padding: 20,
553+
borderRadius: 5
554+
}}
555+
>
556+
<p>My Custom Tooltip</p>
557+
<p>{commit.message.slice(0, 25)}</p>
558+
</div>
559+
)}
560+
/>
561+
486562
<GitLog.Table
487563
className={styles.table}
488564
/>

0 commit comments

Comments
 (0)