Merge pull request #649 from adobe/clamoureux/barAnnotationPadding

feat: added bar annotation padding prop

Author: c-lamoureux

packages/docs/docs/api/visualizations/Bar.md

@@ -260,7 +260,7 @@ The `Annotation` component is used to display a text annotation. The annotation
 ```jsx
 <Chart data={data}>
   <Bar {...props}>
-    <Annotation textKey="textKey" style={{ width: 48 }} />
+    <Annotation textKey="textKey" />
   </Bar>
 </Chart>
 ```
@@ -286,11 +286,17 @@ The `Annotation` component is used to display a text annotation. The annotation
             <td>–</td>
             <td>The key on each value in the data passed to the chart that contains the text to display in the annotation.</td>
         </tr>
+        <tr>
+            <td>padding</td>
+            <td>number</td>
+            <td>4</td>
+            <td>Padding in pixels around the annotation text (applies to both horizontal and vertical padding).</td>
+        </tr>
         <tr>
             <td>style</td>
             <td>\{width: number}</td>
             <td>-</td>
-            <td>Style overrides. Width is used in place of dynamically calculated width.</td>
+            <td>(Deprecated) Style overrides. Width is used in place of dynamically calculated width.</td>
         </tr>
     </tbody>
 </table>

packages/react-spectrum-charts/src/stories/components/Annotation/Annotation.story.tsx

@@ -81,4 +81,18 @@ FixedWidthBar.args = {
   // color: 'operatingSystem',
 };
 
-export { HorizontalBarChart, VerticalBarChart, FixedWidthBar };
+const ReducedPadding = BarAnnotationStory.bind({});
+ReducedPadding.args = {
+  textKey: 'percentLabel',
+  padding: 2,
+  barOrientation: 'horizontal',
+};
+
+const NoPadding = BarAnnotationStory.bind({});
+NoPadding.args = {
+  textKey: 'percentLabel',
+  padding: 0,
+  barOrientation: 'horizontal',
+};
+
+export { HorizontalBarChart, VerticalBarChart, FixedWidthBar, ReducedPadding, NoPadding };

packages/vega-spec-builder/src/bar/barAnnotationUtils.test.ts

@@ -9,7 +9,7 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import { FILTERED_TABLE } from '@spectrum-charts/constants';
+import { ANNOTATION_PADDING, FILTERED_TABLE } from '@spectrum-charts/constants';
 
 import {
   getAnnotationMarks,
@@ -41,32 +41,32 @@ describe('getAnnotationMarks()', () => {
 
 describe('getMinBandwidth()', () => {
   test('should be 48 if bar is vertical', () => {
-    expect(getMinBandwidth('vertical')).toEqual(48);
+    expect(getMinBandwidth('vertical', ANNOTATION_PADDING)).toEqual(48);
   });
   test('should be fontsize + 2*padding if bar is horizontal', () => {
-    expect(getMinBandwidth('horizontal')).toEqual(20);
+    expect(getMinBandwidth('horizontal', ANNOTATION_PADDING)).toEqual(20);
   });
 });
 
 describe('getAnnotationXEncode()', () => {
   test('should use xc and width if width is defined', () => {
-    const xEncode = getAnnotationXEncode(100);
+    const xEncode = getAnnotationXEncode(ANNOTATION_PADDING, 100);
     expect(xEncode).toHaveProperty('xc');
     expect(xEncode).toHaveProperty('width');
   });
   test('should use x and x2 if width is not defined', () => {
-    const xEncode = getAnnotationXEncode();
+    const xEncode = getAnnotationXEncode(ANNOTATION_PADDING);
     expect(xEncode).toHaveProperty('x');
     expect(xEncode).toHaveProperty('x2');
   });
 });
 
 describe('getAnnotationWidth()', () => {
   test('should return hardcoded signal if width is defined', () => {
-    expect(getAnnotationWidth('textLabel', { width: 100 })).toEqual({ value: 100 });
+    expect(getAnnotationWidth('textLabel', ANNOTATION_PADDING, { width: 100 })).toEqual({ value: 100 });
   });
   test('should return signal that gets the label width if width is not defined', () => {
-    const width = getAnnotationWidth('textLabel');
+    const width = getAnnotationWidth('textLabel', ANNOTATION_PADDING);
     expect(width).toHaveProperty('signal');
 
     expect((width as { signal: string }).signal).toContain('getLabelWidth(datum.textLabel,');
@@ -75,17 +75,17 @@ describe('getAnnotationWidth()', () => {
 
 describe('getAnnotationPositionOffset()', () => {
   test('returns 12.5 for vertical orientation', () => {
-    expect(getAnnotationPositionOffset(defaultBarOptions, { value: 12345 })).toEqual('12.5');
+    expect(getAnnotationPositionOffset(defaultBarOptions, { value: 12345 }, ANNOTATION_PADDING)).toEqual('12.5');
   });
 
   test('returns provided value / 2 + 2.5 when value is set and orientation is not vertical', () => {
-    expect(getAnnotationPositionOffset({ ...defaultBarOptions, orientation: 'horizontal' }, { value: 50 })).toEqual(
+    expect(getAnnotationPositionOffset({ ...defaultBarOptions, orientation: 'horizontal' }, { value: 50 }, ANNOTATION_PADDING)).toEqual(
       '27.5'
     );
   });
 
   test('returns the signal string wrapped with parens when signal is set and orientation is not vertical', () => {
-    expect(getAnnotationPositionOffset({ ...defaultBarOptions, orientation: 'horizontal' }, { signal: 'foo' })).toEqual(
+    expect(getAnnotationPositionOffset({ ...defaultBarOptions, orientation: 'horizontal' }, { signal: 'foo' }, ANNOTATION_PADDING)).toEqual(
       '((foo) / 2 + 2.5)'
     );
   });
@@ -95,7 +95,7 @@ describe('getAnnotationMetricAxisPosition()', () => {
   const defaultAnnotationWidth = { value: 22 };
 
   test("defaultBarOptions, should return '${value}1' field", () => {
-    expect(getAnnotationMetricAxisPosition(defaultBarOptions, defaultAnnotationWidth)).toStrictEqual([
+    expect(getAnnotationMetricAxisPosition(defaultBarOptions, defaultAnnotationWidth, ANNOTATION_PADDING)).toStrictEqual([
       {
         signal: `max(scale('yLinear', datum.${defaultBarOptions.metric}1), scale('yLinear', 0) + 12.5)`,
         test: `datum.${defaultBarOptions.metric}1 < 0`,
@@ -105,7 +105,7 @@ describe('getAnnotationMetricAxisPosition()', () => {
   });
   test('horizontal orientation, should return with xLinear scale and min/max properties flipped', () => {
     expect(
-      getAnnotationMetricAxisPosition({ ...defaultBarOptions, orientation: 'horizontal' }, defaultAnnotationWidth)
+      getAnnotationMetricAxisPosition({ ...defaultBarOptions, orientation: 'horizontal' }, defaultAnnotationWidth, ANNOTATION_PADDING)
     ).toStrictEqual([
       {
         test: `datum.${defaultBarOptions.metric}1 < 0`,
@@ -115,7 +115,7 @@ describe('getAnnotationMetricAxisPosition()', () => {
     ]);
   });
   test("stacked with seconday scale, should return '${value}1' field", () => {
-    expect(getAnnotationMetricAxisPosition(defaultBarOptionsWithSecondayColor, defaultAnnotationWidth)).toStrictEqual([
+    expect(getAnnotationMetricAxisPosition(defaultBarOptionsWithSecondayColor, defaultAnnotationWidth, ANNOTATION_PADDING)).toStrictEqual([
       {
         signal: `max(scale('yLinear', datum.${defaultBarOptions.metric}1), scale('yLinear', 0) + 12.5)`,
         test: `datum.${defaultBarOptions.metric}1 < 0`,
@@ -125,7 +125,7 @@ describe('getAnnotationMetricAxisPosition()', () => {
   });
   test("dodged without secondary scale, should return 'value' field", () => {
     expect(
-      getAnnotationMetricAxisPosition({ ...defaultBarOptions, type: 'dodged' }, defaultAnnotationWidth)
+      getAnnotationMetricAxisPosition({ ...defaultBarOptions, type: 'dodged' }, defaultAnnotationWidth, ANNOTATION_PADDING)
     ).toStrictEqual([
       {
         signal: `max(scale('yLinear', datum.${defaultBarOptions.metric}), scale('yLinear', 0) + 12.5)`,
@@ -135,7 +135,7 @@ describe('getAnnotationMetricAxisPosition()', () => {
     ]);
   });
   test("dodged with secondary scale, should return '${value}1' field", () => {
-    expect(getAnnotationMetricAxisPosition(defaultBarOptionsWithSecondayColor, defaultAnnotationWidth)).toStrictEqual([
+    expect(getAnnotationMetricAxisPosition(defaultBarOptionsWithSecondayColor, defaultAnnotationWidth, ANNOTATION_PADDING)).toStrictEqual([
       {
         signal: `max(scale('yLinear', datum.${defaultBarOptions.metric}1), scale('yLinear', 0) + 12.5)`,
         test: `datum.${defaultBarOptions.metric}1 < 0`,

packages/vega-spec-builder/src/bar/barAnnotationUtils.ts

@@ -55,14 +55,15 @@ const getAnnotation = (
  * @returns BarAnnotationSpecOptions
  */
 const applyAnnotationPropDefaults = (
-  { textKey, ...options }: BarAnnotationOptions,
+  { textKey, padding, ...options }: BarAnnotationOptions,
   barOptions: BarSpecOptions,
   dataName: string,
   dimensionScaleName: string,
   dimensionField: string
 ): BarAnnotationSpecOptions => ({
   barOptions,
   textKey: textKey || barOptions.metric,
+  padding: padding ?? ANNOTATION_PADDING,
   dataName,
   dimensionScaleName,
   dimensionField,
@@ -106,6 +107,7 @@ export const getAnnotationMarks = (
  * @returns TextMark
  */
 const getAnnotationTextMark = ({
+  padding,
   barOptions,
   dataName,
   dimensionField,
@@ -114,8 +116,8 @@ const getAnnotationTextMark = ({
   style,
 }: BarAnnotationSpecOptions): TextMark => {
   const { metricAxis, dimensionAxis } = getOrientationProperties(barOptions.orientation);
-  const annotationWidth = getAnnotationWidth(textKey, style);
-  const annotationPosition = getAnnotationMetricAxisPosition(barOptions, annotationWidth);
+  const annotationWidth = getAnnotationWidth(textKey, padding, style);
+  const annotationPosition = getAnnotationMetricAxisPosition(barOptions, annotationWidth, padding);
 
   return {
     name: `${barOptions.name}_annotationText`,
@@ -133,7 +135,7 @@ const getAnnotationTextMark = ({
         [metricAxis]: annotationPosition,
         text: [
           {
-            test: `bandwidth('${dimensionScaleName}') > ${getMinBandwidth(barOptions.orientation)}`,
+            test: `bandwidth('${dimensionScaleName}') > ${getMinBandwidth(barOptions.orientation, padding)}`,
             field: textKey,
           },
         ],
@@ -154,6 +156,7 @@ const getAnnotationTextMark = ({
 const getAnnotationBackgroundMark = ({
   barOptions,
   dimensionScaleName,
+  padding,
   textKey,
   style,
 }: BarAnnotationSpecOptions): RectMark => ({
@@ -164,14 +167,15 @@ const getAnnotationBackgroundMark = ({
   interactive: false,
   encode: {
     enter: {
-      ...getAnnotationXEncode(style?.width),
-      y: { signal: `datum.bounds.y1  - ${ANNOTATION_PADDING}` },
-      y2: { signal: `datum.bounds.y2  + ${ANNOTATION_PADDING}` },
+      ...getAnnotationXEncode(padding, style?.width),
+      y: { signal: `datum.bounds.y1  - ${padding}` },
+      y2: { signal: `datum.bounds.y2  + ${padding}` },
       cornerRadius: { value: 4 },
       fill: [
         {
           test: `datum.datum.${textKey} && bandwidth('${dimensionScaleName}') > ${getMinBandwidth(
-            barOptions.orientation
+            barOptions.orientation,
+            padding
           )}`,
           signal: BACKGROUND_COLOR,
         },
@@ -185,32 +189,32 @@ const getAnnotationBackgroundMark = ({
  * @param orientation
  * @returns number
  */
-export const getMinBandwidth = (orientation: Orientation): number =>
-  orientation === 'vertical' ? 48 : ANNOTATION_FONT_SIZE + 2 * ANNOTATION_PADDING;
+export const getMinBandwidth = (orientation: Orientation, padding: number): number =>
+  orientation === 'vertical' ? 48 : ANNOTATION_FONT_SIZE + 2 * padding;
 
 /**
  * Gets the x position encoding for the annotation background
  * @param width
  * @returns RectEncodeEntry
  */
-export const getAnnotationXEncode = (width?: number): RectEncodeEntry => {
+export const getAnnotationXEncode = (padding: number, width?: number): RectEncodeEntry => {
   if (width) {
     return {
       xc: { signal: '(datum.bounds.x1 + datum.bounds.x2) / 2' },
       width: { value: width },
     };
   }
   return {
-    x: { signal: `datum.bounds.x1 - ${ANNOTATION_PADDING}` },
-    x2: { signal: `datum.bounds.x2 + ${ANNOTATION_PADDING}` },
+    x: { signal: `datum.bounds.x1 - ${padding}` },
+    x2: { signal: `datum.bounds.x2 + ${padding}` },
   };
 };
 
-export const getAnnotationWidth = (textKey: string, style?: BarAnnotationStyleOptions): AnnotationWidth => {
+export const getAnnotationWidth = (textKey: string, padding: number, style?: BarAnnotationStyleOptions): AnnotationWidth => {
   if (style?.width) return { value: style.width };
   return {
     signal: `getLabelWidth(datum.${textKey}, '${ANNOTATION_FONT_WEIGHT}', ${ANNOTATION_FONT_SIZE}) + ${
-      2 * ANNOTATION_PADDING
+      2 * padding
     }`,
   };
 };
@@ -223,12 +227,13 @@ export const getAnnotationWidth = (textKey: string, style?: BarAnnotationStyleOp
  */
 export const getAnnotationPositionOffset = (
   { orientation }: BarSpecOptions,
-  annotationWidth: AnnotationWidth
+  annotationWidth: AnnotationWidth,
+  padding: number
 ): string => {
   const pixelGapFromBaseline = 2.5;
 
   if (orientation === 'vertical') {
-    return `${(2 * ANNOTATION_PADDING + ANNOTATION_FONT_SIZE) / 2 + pixelGapFromBaseline}`;
+    return `${(2 * padding + ANNOTATION_FONT_SIZE) / 2 + pixelGapFromBaseline}`;
   }
 
   if ('value' in annotationWidth) {
@@ -249,12 +254,13 @@ export const getAnnotationPositionOffset = (
  */
 export const getAnnotationMetricAxisPosition = (
   options: BarSpecOptions,
-  annotationWidth: AnnotationWidth
+  annotationWidth: AnnotationWidth,
+  padding: number
 ): ProductionRule<NumericValueRef> => {
   const { type, metric, orientation } = options;
   const field = type === 'stacked' || isDodgedAndStacked(options) ? `${metric}1` : metric;
   const { metricScaleKey: scaleKey } = getOrientationProperties(orientation);
-  const positionOffset = getAnnotationPositionOffset(options, annotationWidth);
+  const positionOffset = getAnnotationPositionOffset(options, annotationWidth, padding);
 
   if (orientation === 'vertical') {
     return [

packages/vega-spec-builder/src/types/marks/supplemental/barAnnotationSpec.types.ts

@@ -17,13 +17,15 @@ export interface BarAnnotationStyleOptions {
 }
 
 export interface BarAnnotationOptions {
+  /** Padding around annotation text. A small amount of padding is always applied based on content */
+  padding?: number
   /** The key in the data that has the text to display */
   textKey?: string;
   /** @deprecated */
   style?: BarAnnotationStyleOptions;
 }
 
-type BarAnnotationOptionsWithDefaults = 'textKey';
+type BarAnnotationOptionsWithDefaults = 'textKey' | 'padding';
 
 export interface BarAnnotationSpecOptions
   extends PartiallyRequired<BarAnnotationOptions, BarAnnotationOptionsWithDefaults> {