feat(pie): improve TypeScript definitions

plouc · Nov 4, 2020 · d0a104e · d0a104e
1 parent 0f3eaed
commit d0a104e
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 51 deletions.
diff --git a/packages/pie/index.d.ts b/packages/pie/index.d.ts
@@ -8,45 +8,75 @@ declare module '@nivo/pie' {
     export type DatumValue = number
     export type DatumFormattedValue = string | number
 
+    // Default datum to use when `id` and `value` properties
+    // use default values, should be redefined if using
+    // a different structure.
     export interface DefaultRawDatum {
         id: DatumId
         value: DatumValue
-        [key: string]: string | number
     }
 
-    export interface Datum<R = DefaultRawDatum> {
+    export interface PieArc {
+        index: number
+        startAngle: number
+        endAngle: number
+        // center angle
+        angle: number
+        angleDeg: number
+        padAngle: number
+    }
+
+    export interface ComputedDatum<R> {
         id: DatumId
         value: DatumValue
         formattedValue: DatumFormattedValue
+        color: string
+        // only defined in case gradients or patterns are used
+        // and the datum matches one of the rules.
+        fill?: string
+        // contains the raw datum as passed to the chart
         data: R
+        arc: PieArc
     }
 
-    export type DatumIdAccessorFunction = (datum: any) => DatumId
-    export type DatumValueAccessorFunction = (datum: any) => DatumValue
+    export type DatumIdAccessorFunction<R> = (datum: R) => DatumId
+    export type DatumValueAccessorFunction<R> = (datum: R) => DatumValue
     export type ValueFormatter = (value: number) => string | number
+    export type LabelAccessorFunction<R> = (datum: ComputedDatum<R>) => string | number
 
-    export interface Data {
-        data: Datum[]
-        id?: string | DatumIdAccessorFunction
-        value?: string | DatumValueAccessorFunction
+    export interface DataProps<R = DefaultRawDatum> {
+        data: R[]
+        id?: string | DatumIdAccessorFunction<R>
+        value?: string | DatumValueAccessorFunction<R>
     }
 
-    export type DatumWithColor = Datum & {
-        color: string
+    export interface PieTooltipProps<R> {
+        datum: ComputedDatum<R>
     }
 
-    export type PieTooltip = DatumWithColor & {
-        label: string | number
+    export type MouseEventHandler<R, T = HTMLCanvasElement> = (
+        datum: ComputedDatum<R>,
+        event: React.MouseEvent<T>
+    ) => void
+
+    export type PieArcGenerator = (arc: PieArc) => string
+
+    export type PieLayerId = 'slices' | 'radialLabels' | 'sliceLabels' | 'legends'
+
+    export interface PieCustomLayerProps<R> {
+        dataWithArc: ComputedDatum<R>[]
+        centerX: number
+        centerY: number
+        radius: number
+        innerRadius: number
+        arcGenerator: PieArcGenerator
     }
 
-    export type AccessorFunc = (datum: Datum) => string
+    export type PieCustomLayer<R> = React.FC<PieCustomLayerProps<R>>
 
-    export type MouseEventHandler<T = HTMLCanvasElement> = (
-        datum: Datum,
-        event: React.MouseEvent<T>
-    ) => void
+    export type PieLayer<R> = PieLayerId | PieCustomLayer<R>
 
-    export type CommonPieProps = MotionProps &
+    export type CommonPieProps<R> = MotionProps &
         Partial<{
             margin: Box
             sortByValue: boolean
@@ -57,61 +87,65 @@ declare module '@nivo/pie' {
             endAngle: number
             fit: boolean
 
-            // border
-            // styling
-            colors: OrdinalColorsInstruction<Datum>
+            // colors, theme and border
+            colors: OrdinalColorsInstruction<Omit<ComputedDatum<R>, 'color' | 'fill'>>
             theme: Theme
             borderWidth: number
-            borderColor: InheritedColorProp<Datum>
+            borderColor: InheritedColorProp<ComputedDatum<R>>
 
             // radial labels
             enableRadialLabels: boolean
-            radialLabel: string | AccessorFunc
+            radialLabel: string | LabelAccessorFunction<R>
             radialLabelsSkipAngle: number
             radialLabelsTextXOffset: number
-            radialLabelsTextColor: InheritedColorProp<DatumWithColor>
+            radialLabelsTextColor: InheritedColorProp<ComputedDatum<R>>
             radialLabelsLinkOffset: number
             radialLabelsLinkDiagonalLength: number
             radialLabelsLinkHorizontalLength: number
             radialLabelsLinkStrokeWidth: number
-            radialLabelsLinkColor: InheritedColorProp<DatumWithColor>
+            radialLabelsLinkColor: InheritedColorProp<ComputedDatum<R>>
 
             // slices labels
             enableSlicesLabels: boolean
-            sliceLabel: string | AccessorFunc
+            sliceLabel: string | LabelAccessorFunction<R>
+            sliceLabelsRadiusOffset: number
             slicesLabelsSkipAngle: number
-            slicesLabelsTextColor: InheritedColorProp<DatumWithColor>
+            slicesLabelsTextColor: InheritedColorProp<ComputedDatum<R>>
 
             // interactivity
             isInteractive: boolean
-            tooltipFormat: string | ValueFormatter
-            tooltip: React.FC<PieTooltip>
+            tooltip: React.FC<PieTooltipProps<R>>
 
             legends: LegendProps[]
         }>
 
-    export type PieSvgProps = Data &
-        CommonPieProps &
-        SvgDefsAndFill<Datum> &
+    export type PieSvgProps<R> = DataProps<R> &
+        CommonPieProps<R> &
+        SvgDefsAndFill<ComputedDatum<R>> &
         Partial<{
-            onClick: MouseEventHandler<SVGPathElement>
-            onMouseEnter: MouseEventHandler<SVGPathElement>
-            onMouseLeave: MouseEventHandler<SVGPathElement>
+            layers: PieLayer<R>[]
+            onClick: MouseEventHandler<R, SVGPathElement>
+            onMouseEnter: MouseEventHandler<R, SVGPathElement>
+            onMouseLeave: MouseEventHandler<R, SVGPathElement>
             role: string
         }>
 
-    export class Pie extends React.Component<PieSvgProps & Dimensions> {}
-    export class ResponsivePie extends React.Component<PieSvgProps> {}
+    export class Pie<R = DefaultRawDatum> extends React.Component<PieSvgProps<R> & Dimensions> {}
+    export class ResponsivePie<R = DefaultRawDatum> extends React.Component<PieSvgProps<R>> {}
 
-    export type PieCanvasProps = Data &
-        CommonPieProps &
+    export type PieCanvasProps<R> = DataProps<R> &
+        CommonPieProps<R> &
         Partial<{
             pixelRatio: number
-            onClick: MouseEventHandler
-            onMouseEnter: MouseEventHandler
-            onMouseLeave: MouseEventHandler
+            onClick: MouseEventHandler<R, HTMLCanvasElement>
+            onMouseEnter: MouseEventHandler<R, HTMLCanvasElement>
+            onMouseLeave: MouseEventHandler<R, HTMLCanvasElement>
         }>
 
-    export class PieCanvas extends React.Component<PieCanvasProps & Dimensions> {}
-    export class ResponsivePieCanvas extends React.Component<PieCanvasProps> {}
+    export class PieCanvas<R = DefaultRawDatum> extends React.Component<
+        PieCanvasProps<R> & Dimensions
+    > {}
+    export class ResponsivePieCanvas<R = DefaultRawDatum> extends React.Component<
+        PieCanvasProps<R>
+    > {}
 }
diff --git a/website/src/data/components/pie/props.js b/website/src/data/components/pie/props.js
@@ -558,17 +558,16 @@ const props = [
         help: 'Custom tooltip component',
         description: `
             A function allowing complete tooltip customisation,
-            it must return a valid HTML
-            element and will receive the following data:
+            it must return a valid HTML element and will receive
+            the following props:
+            
             \`\`\`
             {
-                id:    {string|number},
-                value: number,
-                label: {string|number},
-                color: string
+                datum: PieComputedDatum
             }
             \`\`\`
-            You can customize the style of the tooltip using
+            
+            You can also customize the style of the tooltip using
             the \`theme.tooltip\` object.
         `,
     },