[core] fix(SectionCard): rename component, fix Sass variable names (#…

…6272)
palantir · Jul 13, 2023 · 68d563c · 68d563c · adidahiya · Jul 13, 2023
1 parent 85f0d68
commit 68d563c
Show file tree

Hide file tree

Showing 7 changed files with 101 additions and 49 deletions.
diff --git a/packages/core/src/common/classes.ts b/packages/core/src/common/classes.ts
@@ -226,7 +226,7 @@ export const SECTION_HEADER_SUB_TITLE = `${SECTION_HEADER}-sub-title`;
 export const SECTION_HEADER_DIVIDER = `${SECTION_HEADER}-divider`;
 export const SECTION_HEADER_TABS = `${SECTION_HEADER}-tabs`;
 export const SECTION_HEADER_RIGHT = `${SECTION_HEADER}-right`;
-export const SECTION_PANEL = `${SECTION}-panel`;
+export const SECTION_CARD = `${SECTION}-card`;
 
 export const NAVBAR = `${NS}-navbar`;
 export const NAVBAR_GROUP = `${NAVBAR}-group`;

diff --git a/packages/core/src/components/index.ts b/packages/core/src/components/index.ts
@@ -97,8 +97,8 @@ export { ResizeEntry, ResizeSensor, ResizeSensorProps } from "./resize-sensor/re
 export { HandleHtmlProps, HandleInteractionKind, HandleProps, HandleType } from "./slider/handleProps";
 export { MultiSlider, MultiSliderProps, SliderBaseProps } from "./slider/multiSlider";
 export { NumberRange, RangeSlider, RangeSliderProps } from "./slider/rangeSlider";
-export { Section, SectionProps } from "./section/section";
-export { SectionPanel, SectionPanelProps } from "./section/sectionPanel";
+export { Section, SectionElevation, SectionProps } from "./section/section";
+export { SectionCard, SectionCardProps } from "./section/sectionPanel";
 export { Slider, SliderProps } from "./slider/slider";
 export { Spinner, SpinnerProps, SpinnerSize } from "./spinner/spinner";
 export { Tab, TabId, TabProps } from "./tabs/tab";

diff --git a/packages/core/src/components/section/_section.scss b/packages/core/src/components/section/_section.scss
@@ -2,14 +2,14 @@
 @import "../../common/variables";
 
 $section-min-height: $pt-grid-size * 5 !default;
-$section-vertical-padding: $pt-grid-size !default;
-$section-horizontal-padding: $pt-grid-size * 2 !default;
-$section-panel-padding: $pt-grid-size * 2 !default;
+$section-padding-vertical: $pt-grid-size !default;
+$section-padding-horizontal: $pt-grid-size * 2 !default;
+$section-card-padding: $pt-grid-size * 2 !default;
 
-$section-compact-min-height: $pt-grid-size * 4 !default;
-$section-compact-vertical-padding: 7px !default;
-$section-compact-horizontal-padding: 15px !default;
-$section-compact-panel-padding: $pt-grid-size * 1.5 !default;
+$section-min-height-compact: $pt-grid-size * 4 !default;
+$section-padding-compact-vertical: 7px !default;
+$section-padding-compact-horizontal: 15px !default;
+$section-card-padding-compact: $pt-grid-size * 1.5 !default;
 
 .#{$ns}-section {
   overflow: hidden;
@@ -23,7 +23,7 @@ $section-compact-panel-padding: $pt-grid-size * 1.5 !default;
     gap: $pt-grid-size * 2;
     justify-content: space-between;
     min-height: $section-min-height;
-    padding: 0 $section-horizontal-padding;
+    padding: 0 $section-padding-horizontal;
     position: relative;
     width: 100%;
 
@@ -36,7 +36,7 @@ $section-compact-panel-padding: $pt-grid-size * 1.5 !default;
       align-items: center;
       display: flex;
       gap: $pt-grid-size;
-      padding: $section-vertical-padding 0;
+      padding: $section-padding-vertical 0;
     }
 
     &-title {
@@ -74,9 +74,9 @@ $section-compact-panel-padding: $pt-grid-size * 1.5 !default;
     }
   }
 
-  &-panel {
+  &-card {
     &.#{$ns}-padded {
-      padding: $section-panel-padding;
+      padding: $section-card-padding;
     }
 
     &:not(:last-child) {
@@ -97,16 +97,16 @@ $section-compact-panel-padding: $pt-grid-size * 1.5 !default;
 
   &.#{$ns}-compact {
     .#{$ns}-section-header {
-      min-height: $section-compact-min-height;
-      padding: 0 $section-compact-horizontal-padding;
+      min-height: $section-min-height-compact;
+      padding: 0 $section-padding-compact-horizontal;
 
       &-left {
-        padding: $section-compact-vertical-padding 0;
+        padding: $section-padding-compact-vertical 0;
       }
     }
 
-    .#{$ns}-section-panel.#{$ns}-padded {
-      padding: $section-compact-panel-padding;
+    .#{$ns}-section-card.#{$ns}-padded {
+      padding: $section-card-padding-compact;
     }
   }
 }
diff --git a/packages/core/src/components/section/section.md b/packages/core/src/components/section/section.md
@@ -2,7 +2,7 @@
 
 The __Section__ component can be used to contain, structure, and create hierarchy for information in your UI. It makes use of some concepts from other more atomic Blueprint components:
 
-- The overall appearance looks like a [__Card__](#core/components/card)
+- The overall appearance looks like a [__Card__](#core/components/card) (with limited `elevation` options)
 - Contents may be collapsible like the [__Collapse__](#core/components/collapse) component
 
 @reactExample SectionExample
@@ -11,15 +11,15 @@ The __Section__ component can be used to contain, structure, and create hierarch
 
 @interface SectionProps
 
-@## Section panel
+@## Section card
 
-Multiple __SectionPanel__ child components can be added under one __Section__, they will be stacked vertically. This layout can be used to further group information.
+Multiple __SectionCard__ child components can be added under one __Section__, they will be stacked vertically. This layout can be used to further group information.
 
 ```tsx
 <Section>
-    <SectionPanel>{/* ... */}</SectionPanel>
-    <SectionPanel>{/* ... */}</SectionPanel>
+    <SectionCard>{/* ... */}</SectionCard>
+    <SectionCard>{/* ... */}</SectionCard>
 </Section>
 ```
 
-@interface SectionPanelProps
+@interface SectionCardProps
diff --git a/packages/core/src/components/section/section.tsx b/packages/core/src/components/section/section.tsx
@@ -26,6 +26,14 @@ import { Collapse, CollapseProps } from "../collapse/collapse";
 import { H6 } from "../html/html";
 import { Icon } from "../icon/icon";
 
+/**
+ * Subset of {@link Elevation} options which are visually supported by the {@link Section} component.
+ *
+ * Note that an elevation greater than 1 creates too much visual clutter/noise in the UI, especially when
+ * multiple Sections are shown on a single page.
+ */
+export type SectionElevation = typeof Elevation.ZERO | typeof Elevation.ONE;
+
 export interface SectionProps extends Props, Omit<HTMLDivProps, "title">, React.RefAttributes<HTMLDivElement> {
     /**
      * Whether this section's contents should be collapsible.
@@ -51,6 +59,13 @@ export interface SectionProps extends Props, Omit<HTMLDivProps, "title">, React.
      */
     compact?: boolean;
 
+    /**
+     * Visual elevation of this container element.
+     *
+     * @default Elevation.ZERO
+     */
+    elevation?: SectionElevation;
+
     /**
      * Name of a Blueprint UI icon (or an icon element) to render in the section's header.
      * Note that the header will only be rendered if `title` is provided.
@@ -87,11 +102,12 @@ export const Section: React.FC<SectionProps> = React.forwardRef((props, ref) =>
         collapseProps,
         collapsible,
         compact,
+        elevation,
         icon,
         rightElement,
         subtitle,
         title,
-        ...cardProps
+        ...htmlProps
     } = props;
     const [isCollapsed, setIsCollapsed] = React.useState<boolean>(collapseProps?.defaultIsOpen ?? false);
     const toggleIsCollapsed = React.useCallback(() => setIsCollapsed(!isCollapsed), [isCollapsed]);
@@ -101,13 +117,13 @@ export const Section: React.FC<SectionProps> = React.forwardRef((props, ref) =>
 
     return (
         <Card
-            elevation={Elevation.ZERO}
             className={classNames(className, Classes.SECTION, {
                 [Classes.COMPACT]: compact,
                 [Classes.SECTION_COLLAPSED]: collapsible && isCollapsed,
             })}
+            elevation={elevation}
             ref={ref}
-            {...cardProps}
+            {...htmlProps}
         >
             <div
                 role={collapsible ? "button" : undefined}
@@ -161,5 +177,6 @@ export const Section: React.FC<SectionProps> = React.forwardRef((props, ref) =>
 });
 Section.defaultProps = {
     compact: false,
+    elevation: Elevation.ZERO,
 };
 Section.displayName = `${DISPLAYNAME_PREFIX}.Section`;
diff --git a/packages/core/src/components/section/sectionPanel.tsx b/packages/core/src/components/section/sectionPanel.tsx
@@ -20,7 +20,7 @@ import * as React from "react";
 import { Classes } from "../../common";
 import { DISPLAYNAME_PREFIX, HTMLDivProps, Props } from "../../common/props";
 
-export interface SectionPanelProps extends Props, HTMLDivProps, React.RefAttributes<HTMLDivElement> {
+export interface SectionCardProps extends Props, HTMLDivProps, React.RefAttributes<HTMLDivElement> {
     /**
      * Whether to apply visual padding inside the content container element.
      *
@@ -30,20 +30,20 @@ export interface SectionPanelProps extends Props, HTMLDivProps, React.RefAttribu
 }
 
 /**
- * Section panel component.
+ * Section card component.
  *
- * @see https://blueprintjs.com/docs/#core/components/section.section-panel
+ * @see https://blueprintjs.com/docs/#core/components/section.section-card
  */
-export const SectionPanel: React.FC<SectionPanelProps> = React.forwardRef((props, ref) => {
+export const SectionCard: React.FC<SectionCardProps> = React.forwardRef((props, ref) => {
     const { className, children, padded, ...htmlProps } = props;
-    const classes = classNames(Classes.SECTION_PANEL, { [Classes.PADDED]: padded }, className);
+    const classes = classNames(Classes.SECTION_CARD, { [Classes.PADDED]: padded }, className);
     return (
         <div className={classes} ref={ref} {...htmlProps}>
             {children}
         </div>
     );
 });
-SectionPanel.defaultProps = {
+SectionCard.defaultProps = {
     padded: true,
 };
-SectionPanel.displayName = `${DISPLAYNAME_PREFIX}.SectionPanel`;
+SectionCard.displayName = `${DISPLAYNAME_PREFIX}.SectionCard`;
diff --git a/packages/docs-app/src/examples/core-examples/sectionExample.tsx b/packages/docs-app/src/examples/core-examples/sectionExample.tsx
@@ -17,15 +17,28 @@
 import dedent from "dedent";
 import * as React from "react";
 
-import { Button, Classes, EditableText, H5, Section, SectionPanel, Switch } from "@blueprintjs/core";
+import {
+    Button,
+    Classes,
+    EditableText,
+    Elevation,
+    H5,
+    Label,
+    Section,
+    SectionCard,
+    SectionElevation,
+    Slider,
+    Switch,
+} from "@blueprintjs/core";
 import { Example, ExampleProps } from "@blueprintjs/docs-theme";
 import { IconNames } from "@blueprintjs/icons";
 
 export interface SectionExampleState {
     collapsible: boolean;
+    elevation: SectionElevation;
     hasDescription: boolean;
     hasIcon: boolean;
-    hasMultiplePanels: boolean;
+    hasMultipleCards: boolean;
     hasRightElement: boolean;
     isCompact: boolean;
     isPanelPadded: boolean;
@@ -41,9 +54,10 @@ const BASIL_DESCRIPTION_TEXT = dedent`
 export class SectionExample extends React.PureComponent<ExampleProps, SectionExampleState> {
     public state: SectionExampleState = {
         collapsible: false,
+        elevation: Elevation.ZERO,
         hasDescription: false,
         hasIcon: false,
-        hasMultiplePanels: false,
+        hasMultipleCards: false,
         hasRightElement: true,
         isCompact: false,
         isPanelPadded: true,
@@ -52,8 +66,16 @@ export class SectionExample extends React.PureComponent<ExampleProps, SectionExa
     private editableTextRef = React.createRef<HTMLDivElement>();
 
     public render() {
-        const { collapsible, hasDescription, hasIcon, hasRightElement, hasMultiplePanels, isCompact, isPanelPadded } =
-            this.state;
+        const {
+            collapsible,
+            elevation,
+            hasDescription,
+            hasIcon,
+            hasRightElement,
+            hasMultipleCards,
+            isCompact,
+            isPanelPadded,
+        } = this.state;
 
         const options = (
             <>
@@ -63,15 +85,25 @@ export class SectionExample extends React.PureComponent<ExampleProps, SectionExa
                 <Switch checked={hasDescription} label="Description" onChange={this.toggleHasDescription} />
                 <Switch checked={hasRightElement} label="Right element" onChange={this.toggleHasRightElement} />
                 <Switch checked={collapsible} label="Collapsible" onChange={this.toggleCollapsible} />
+                <Label>
+                    Elevation
+                    <Slider
+                        max={1}
+                        showTrackFill={false}
+                        value={elevation}
+                        onChange={this.handleElevationChange}
+                        handleHtmlProps={{ "aria-label": "Section elevation" }}
+                    />
+                </Label>
 
                 <H5>Children</H5>
                 <Switch
-                    checked={hasMultiplePanels}
-                    label="Multiple section panels"
+                    checked={hasMultipleCards}
+                    label="Multiple section cards"
                     onChange={this.toggleMultiplePanels}
                 />
 
-                <H5>SectionPanel Props</H5>
+                <H5>SectionCard Props</H5>
                 <Switch checked={isPanelPadded} label="Padded" onChange={this.togglePanelIsPadded} />
             </>
         );
@@ -102,9 +134,9 @@ export class SectionExample extends React.PureComponent<ExampleProps, SectionExa
         return (
             <Example options={options} {...this.props}>
                 <Section
+                    collapsible={collapsible}
                     compact={isCompact}
-                    title="Basil"
-                    subtitle={hasDescription ? "Ocimum basilicum" : undefined}
+                    elevation={elevation}
                     icon={hasIcon ? IconNames.BOOK : undefined}
                     rightElement={
                         hasRightElement ? (
@@ -116,10 +148,11 @@ export class SectionExample extends React.PureComponent<ExampleProps, SectionExa
                             />
                         ) : undefined
                     }
-                    collapsible={collapsible}
+                    subtitle={hasDescription ? "Ocimum basilicum" : undefined}
+                    title="Basil"
                 >
-                    <SectionPanel padded={isPanelPadded}>{descriptionContent}</SectionPanel>
-                    {hasMultiplePanels && <SectionPanel padded={isPanelPadded}>{metadataContent}</SectionPanel>}
+                    <SectionCard padded={isPanelPadded}>{descriptionContent}</SectionCard>
+                    {hasMultipleCards && <SectionCard padded={isPanelPadded}>{metadataContent}</SectionCard>}
                 </Section>
             </Example>
         );
@@ -133,12 +166,14 @@ export class SectionExample extends React.PureComponent<ExampleProps, SectionExa
 
     private toggleHasRightElement = () => this.setState({ hasRightElement: !this.state.hasRightElement });
 
-    private toggleMultiplePanels = () => this.setState({ hasMultiplePanels: !this.state.hasMultiplePanels });
+    private toggleMultiplePanels = () => this.setState({ hasMultipleCards: !this.state.hasMultipleCards });
 
     private toggleCollapsible = () => this.setState({ collapsible: !this.state.collapsible });
 
     private togglePanelIsPadded = () => this.setState({ isPanelPadded: !this.state.isPanelPadded });
 
+    private handleElevationChange = (elevation: SectionElevation) => this.setState({ elevation });
+
     private handleEditContent = (event: React.MouseEvent) => {
         // prevent this event from toggling the collapse state
         event.stopPropagation();