[PLAY-1682] Create Global Gap Prop (#4067)

Adds new gap prop to global props list. [[PLAY-1682]](https://runway.powerhrg.com/backlog_items/PLAY-1682) <img width="794" alt="Screenshot 2025-01-03 at 11 52 43 AM" src="https://github.com/user-attachments/assets/6d8f9e67-9c8b-4866-9056-da7236de5ac2" /> <img width="794" alt="Screenshot 2025-01-03 at 11 53 37 AM" src="https://github.com/user-attachments/assets/433846e8-a7e5-46c1-a25c-7de1f44d2b1c" /> <img width="796" alt="Screenshot 2025-01-03 at 11 52 22 AM" src="https://github.com/user-attachments/assets/689a1a8c-c40d-4ae8-a8da-16e844c7e366" /> #### Checklist: - [x] **LABELS** Add a label: `enhancement`, `bug`, `improvement`, `new kit`, `deprecated`, or `breaking`. See [Changelog & Labels](https://github.com/powerhome/playbook/wiki/Changelog-&-Labels) for details. - [x] **DEPLOY** I have added the `milano` label to show I'm ready for a review.
powerhome · Jan 8, 2025 · 9158c79 · 9158c79
1 parent 7c75f93
commit 9158c79
Show file tree

Hide file tree

Showing 13 changed files with 98 additions and 31 deletions.
diff --git a/playbook-website/app/javascript/components/AvailableProps/globalPropsValues.ts b/playbook-website/app/javascript/components/AvailableProps/globalPropsValues.ts
@@ -78,6 +78,11 @@ const globalPropsValues = [
     type: "union",
     values: '"wrap" | "nowrap" | "wrapReverse"'
   },
+  {
+    prop: "gap",
+    type: "union",
+    values: '"none" | "xxs" | "xs" | "sm" | "md" | "lg" | "xl"'
+  },
   {
     prop: "htmlOptions",
     type: "object",

diff --git a/playbook-website/app/javascript/components/VisualGuidelines/Examples/FlexBox.tsx b/playbook-website/app/javascript/components/VisualGuidelines/Examples/FlexBox.tsx
@@ -15,7 +15,8 @@ const PROPS = {
   flex: ['none', 'initial', 'auto', '1'],
   flexGrow: ['0', '1'],
   flexShrink: ['0', '1'],
-  order: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', 'none']
+  order: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', 'none'],
+  gap: ['none', 'xxs', 'xs', 'sm', 'md', 'lg', 'xl']
 }
 const TABLE_HEADERS = ['Props', 'Screen Sizes', 'Values']
 

diff --git a/playbook/app/entrypoints/playbook.scss b/playbook/app/entrypoints/playbook.scss
@@ -128,3 +128,4 @@
 @import 'utilities/truncate';
 @import 'utilities/vertical_align';
 @import 'utilities/height';
+@import 'utilities/gap';
diff --git a/playbook/app/pb_kits/playbook/pb_timeline/_timeline.tsx b/playbook/app/pb_kits/playbook/pb_timeline/_timeline.tsx
@@ -20,7 +20,7 @@ type TimelineProps = {
   id?: string,
   orientation?: string,
   showDate?: boolean,
-  gap?: 'xs' | 'sm' | 'md' | 'lg' | 'none',
+  itemGap?: 'xs' | 'sm' | 'md' | 'lg' | 'none',
 } & GlobalProps
 
 const Timeline = ({
@@ -32,15 +32,15 @@ const Timeline = ({
   id,
   orientation = 'horizontal',
   showDate = false,
-  gap = 'none',
+  itemGap = 'none',
   ...props
 }: TimelineProps): React.ReactElement => {
   const ariaProps = buildAriaProps(aria)
   const dataProps = buildDataProps(data)
   const htmlProps = buildHtmlProps(htmlOptions)
   const dateStyle = showDate === true ? '_with_date' : ''
-  const gapStyle = gap === 'none' ? '' : `gap_${gap}`
-  const timelineCss = buildCss('pb_timeline_kit', `${orientation}`, dateStyle, gapStyle)
+  const itemGapStyle = itemGap === 'none' ? '' : `gap_${itemGap}`
+  const timelineCss = buildCss('pb_timeline_kit', `${orientation}`, dateStyle, itemGapStyle)
 
   return (
     <div
@@ -60,4 +60,4 @@ Timeline.Step = TimelineStep
 Timeline.Label = TimelineLabel
 Timeline.Detail = TimelineDetail
 
-export default Timeline
+export default Timeline
diff --git a/playbook/app/pb_kits/playbook/pb_timeline/docs/_timeline_with_gap.html.erb b/playbook/app/pb_kits/playbook/pb_timeline/docs/_timeline_with_gap.html.erb
@@ -1,6 +1,6 @@
 <%= pb_rails("flex", props: { justify: "evenly" }) do %>
     <%= pb_rails("flex/flex_item") do %>
-        <%= pb_rails("timeline", props: {orientation: "vertical", gap: "xs"}) do %>
+        <%= pb_rails("timeline", props: {orientation: "vertical", item_gap: "xs"}) do %>
             <%= pb_rails("timeline/item", props: {icon: "user", icon_color: "royal"}) do %>
                 <%= pb_rails("body", props: {
                     text: "Conversation started",
@@ -23,7 +23,7 @@
     <% end %>
 
     <%= pb_rails("flex/flex_item") do %>
-        <%= pb_rails("timeline", props: {orientation: "vertical", gap: "sm"}) do %>
+        <%= pb_rails("timeline", props: {orientation: "vertical", item_gap: "sm"}) do %>
             <%= pb_rails("timeline/item", props: {icon: "user", icon_color: "royal"}) do %>
                 <%= pb_rails("body", props: {
                     text: "Conversation started",
@@ -46,7 +46,7 @@
     <% end %>
 
     <%= pb_rails("flex/flex_item") do %>
-        <%= pb_rails("timeline", props: {orientation: "vertical", gap: "md"}) do %>
+        <%= pb_rails("timeline", props: {orientation: "vertical", item_gap: "md"}) do %>
             <%= pb_rails("timeline/item", props: {icon: "user", icon_color: "royal"}) do %>
                 <%= pb_rails("body", props: {
                     text: "Conversation started",
@@ -69,7 +69,7 @@
     <% end %>
 
     <%= pb_rails("flex/flex_item") do %>
-        <%= pb_rails("timeline", props: {orientation: "vertical", gap: "lg"}) do %>
+        <%= pb_rails("timeline", props: {orientation: "vertical", item_gap: "lg"}) do %>
             <%= pb_rails("timeline/item", props: {icon: "user", icon_color: "royal"}) do %>
                 <%= pb_rails("body", props: {
                     text: "Conversation started",
@@ -91,4 +91,3 @@
         <% end %>
     <% end %>
 <% end %>
-
diff --git a/playbook/app/pb_kits/playbook/pb_timeline/docs/_timeline_with_gap.jsx b/playbook/app/pb_kits/playbook/pb_timeline/docs/_timeline_with_gap.jsx
@@ -10,7 +10,7 @@ const TimelineWithGap = (props) => (
     <Flex justify="evenly">
     <FlexItem>
         <Timeline
-            gap="xs"
+            itemGap="xs"
             orientation="vertical"
         >
           <Timeline.Item
@@ -51,7 +51,7 @@ const TimelineWithGap = (props) => (
       </FlexItem>
       <FlexItem>
         <Timeline
-            gap="sm"
+            itemGap="sm"
             orientation="vertical"
         >
           <Timeline.Item
@@ -92,7 +92,7 @@ const TimelineWithGap = (props) => (
       </FlexItem>
       <FlexItem>
         <Timeline
-            gap="md"
+            itemGap="md"
             orientation="vertical"
         >
           <Timeline.Item
@@ -134,7 +134,7 @@ const TimelineWithGap = (props) => (
       </FlexItem>
       <FlexItem>
         <Timeline
-            gap="lg"
+            itemGap="lg"
             orientation="vertical"
         >
           <Timeline.Item

diff --git a/playbook/app/pb_kits/playbook/pb_timeline/docs/_timeline_with_gap.md b/playbook/app/pb_kits/playbook/pb_timeline/docs/_timeline_with_gap.md
@@ -1 +1 @@
-Use the optional `gap` prop to render the timeline kit with adjusted spacing between nodes. The `gap` prop will only work when utilized with a vertical timeline. Horizontal timelines will show no difference in spacing.
+Use the optional `itemGap` prop to render the timeline kit with adjusted spacing between nodes. The `itemGap` prop will only work when utilized with a vertical timeline. Horizontal timelines will show no difference in spacing.
diff --git a/playbook/app/pb_kits/playbook/pb_timeline/timeline.rb b/playbook/app/pb_kits/playbook/pb_timeline/timeline.rb
@@ -8,15 +8,15 @@ class Timeline < Playbook::KitBase
                          default: "horizontal"
       prop :show_date, type: Playbook::Props::Boolean,
                        default: false
-      prop :gap, type: Playbook::Props::Enum,
-                 values: %w[xs sm md lg none],
-                 default: "none"
+      prop :item_gap, type: Playbook::Props::Enum,
+                      values: %w[xs sm md lg none],
+                      default: "none"
 
       def classname
         generate_classname("pb_timeline_kit",
                            orientation,
                            date_class,
-                           gap_class)
+                           item_gap_class)
       end
 
     private
@@ -25,8 +25,8 @@ def date_class
         show_date ? "with_date" : nil
       end
 
-      def gap_class
-        gap == "none" ? nil : "gap_#{gap}"
+      def item_gap_class
+        item_gap == "none" ? nil : "gap_#{item_gap}"
       end
     end
   end

diff --git a/playbook/app/pb_kits/playbook/utilities/_gap.scss b/playbook/app/pb_kits/playbook/utilities/_gap.scss
@@ -0,0 +1,29 @@
+@import "spacing";
+
+.gap_none {
+  gap: 0;
+}
+
+.gap_xxs {
+  gap: $space_xxs;
+}
+
+.gap_xs {
+  gap: $space_xs;
+}
+
+.gap_sm {
+  gap: $space_sm;
+}
+
+.gap_md {
+  gap: $space_md;
+}
+
+.gap_lg {
+  gap: $space_lg;
+}
+
+.gap_xl {
+  gap: $space_xl;
+}
diff --git a/playbook/app/pb_kits/playbook/utilities/globalPropNames.mjs b/playbook/app/pb_kits/playbook/utilities/globalPropNames.mjs
@@ -27,6 +27,7 @@ export default [
   "overflow",
   "order",
   "numberSpacing",
+  "gap",
   "maxWidth",
   "minWidth",
   "width",

diff --git a/playbook/app/pb_kits/playbook/utilities/globalProps.ts b/playbook/app/pb_kits/playbook/utilities/globalProps.ts
@@ -108,6 +108,10 @@ type MinWidth = {
   minWidth?: string,
 }
 
+type Gap = {
+  gap?: string,
+}
+
 type NumberSpacing = {
   numberSpacing?: "tabular",
 }
@@ -196,7 +200,7 @@ type MinHeight = {
 export type GlobalProps = AlignContent & AlignItems & AlignSelf &
   BorderRadius & Cursor & Dark & Display & DisplaySizes & Flex & FlexDirection &
   FlexGrow & FlexShrink & FlexWrap & JustifyContent & JustifySelf &
-  LineHeight & Margin & Width & MinWidth & MaxWidth & NumberSpacing & Order & Overflow & Padding &
+  LineHeight & Margin & Width & MinWidth & MaxWidth & Gap & NumberSpacing & Order & Overflow & Padding &
   Position & Shadow & TextAlign & Truncate & VerticalAlign & ZIndex & { hover?: string } & Top & Right & Bottom & Left & Height & MaxHeight & MinHeight;
 
 const getResponsivePropClasses = (prop: {[key: string]: string}, classPrefix: string) => {
@@ -372,6 +376,11 @@ const PROP_CATEGORIES: {[key:string]: (props: {[key: string]: any}) => string} =
     css += maxWidth ? `max_width_${filterClassName(maxWidth)} ` : ''
     return css.trimEnd()
   },
+  gapProps: ({ gap }: Gap) => {
+    let css = ''
+    css += gap ? `gap_${gap} ` : ''
+    return css.trimEnd()
+  },
   minHeightProps: ({ minHeight }: MinHeight) => {
     const heightValues = ["auto", "xs", "sm", "md", "lg", "xl", "xxl", "xxxl"]
     if (heightValues.includes(minHeight)) {
@@ -530,15 +539,15 @@ const PROP_CATEGORIES: {[key:string]: (props: {[key: string]: any}) => string} =
   },
 
 
-  topProps: ({top}) => getPositioningPropsClasses('top', top), 
+  topProps: ({top}) => getPositioningPropsClasses('top', top),
+
+  rightProps: ({right}) => getPositioningPropsClasses('right', right),
 
-  rightProps: ({right}) => getPositioningPropsClasses('right', right), 
+  bottomProps:({bottom}) =>  getPositioningPropsClasses('bottom', bottom),
 
-  bottomProps:({bottom}) =>  getPositioningPropsClasses('bottom', bottom), 
-
   leftProps: ({left}) => getPositioningPropsClasses('left', left),
-    
-  
+
+
   textAlignProps: ({ textAlign }: TextAlign) => {
     if (typeof textAlign === 'object') {
       return getResponsivePropClasses(textAlign, 'text_align')
@@ -558,15 +567,15 @@ const PROP_CATEGORIES: {[key:string]: (props: {[key: string]: any}) => string} =
 
 const PROP_INLINE_CATEGORIES: {[key:string]: (props: {[key: string]: any}) => {[key: string]: any}} = {
   heightProps: ({ height }: Height) => {
-    return height ? { height } : {}; 
+    return height ? { height } : {};
   },
 
   maxHeightProps: ({ maxHeight }: MaxHeight) => {
     return maxHeight ? { maxHeight } : {};
   },
 
   minHeightProps: ({ minHeight }: MinHeight) => {
-    return minHeight ? { minHeight } : {}; 
+    return minHeight ? { minHeight } : {};
   },
 }
 

diff --git a/playbook/lib/playbook/classnames.rb b/playbook/lib/playbook/classnames.rb
@@ -16,6 +16,7 @@ def generate_classname(*name_parts, separator: "_")
         width_props,
         min_width_props,
         max_width_props,
+        gap_props,
         z_index_props,
         number_spacing_props,
         shadow_props,

diff --git a/playbook/lib/playbook/spacing.rb b/playbook/lib/playbook/spacing.rb
@@ -3,6 +3,7 @@
 module Playbook
   module Spacing
     def self.included(base)
+      base.prop :gap
       base.prop :margin
       base.prop :margin_bottom
       base.prop :margin_left
@@ -52,6 +53,16 @@ def width_values
       %w[0% xs sm md lg xl xxl 0 none 100%]
     end
 
+    def gap_values
+      %w[none xxs xs sm md lg xl]
+    end
+
+    def gap_options
+      {
+        gap: "gap",
+      }
+    end
+
     def spacing_options
       {
         margin: "m",
@@ -146,5 +157,15 @@ def width_props
         "width_#{filter_classname(width_value)}" if width_values.include? width_value
       end.compact.join(" ")
     end
+
+    def gap_props
+      selected_gap_props = gap_options.keys.select { |sk| try(sk) }
+      return nil unless selected_gap_props.present?
+
+      selected_gap_props.map do |k|
+        gap_value = send(k)
+        "gap_#{gap_value}" if gap_values.include? gap_value
+      end.compact.join(" ")
+    end
   end
 end
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		Use the optional `gap` prop to render the timeline kit with adjusted spacing between nodes. The `gap` prop will only work when utilized with a vertical timeline. Horizontal timelines will show no difference in spacing.
		Use the optional `itemGap` prop to render the timeline kit with adjusted spacing between nodes. The `itemGap` prop will only work when utilized with a vertical timeline. Horizontal timelines will show no difference in spacing.