[TR#146] Text Pair (#209)

This PR adds a new component, Text Pair! It also removes the gap override option and docs from the breadcrumbs component as it did not work as intended.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolemodel/optics",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Optics is an scss package that provides base styles and components that can be integrated and customized in a variety of projects.",
   "main": "dist/scss/optics.scss",
   "scripts": {

src/components/breadcrumbs.scss

@@ -9,7 +9,7 @@
   display: flex;
   flex-wrap: wrap;
   align-items: baseline;
-  gap: var(--op-gap, var(--op-space-x-small));
+  gap: var(--op-space-x-small);
 
   // Elements
   .breadcrumbs__link {

src/components/index.scss

@@ -20,4 +20,5 @@
 @import 'tab';
 @import 'table';
 @import 'tag';
+@import 'text_pair';
 @import 'tooltip';

src/components/text_pair.scss

@@ -0,0 +1,59 @@
+%text-pair-global {
+  // Public API (allowed to be overridden)
+  --_op-text-pair-font-size-small: var(--op-font-small);
+  --_op-text-pair-font-size-medium: var(--op-font-medium);
+  --_op-text-pair-font-size-large: var(--op-font-large);
+
+  // Private API (don't touch these)
+  --__op-text-pair-title-font-size: var(--_op-text-pair-font-size-medium);
+  --__op-text-pair-subtitle-font-size: var(--_op-text-pair-font-size-small);
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--op-space-x-small);
+
+  &.text-pair--inline {
+    flex-direction: row;
+    align-items: baseline;
+  }
+
+  .text-pair__title {
+    font-size: var(--__op-text-pair-title-font-size);
+    font-weight: var(--op-font-weight-semi-bold);
+    line-height: var(--op-line-height-dense);
+
+    &.text-pair__title--small {
+      --__op-text-pair-title-font-size: var(--_op-text-pair-font-size-small);
+    }
+
+    &.text-pair__title--medium {
+      --__op-text-pair-title-font-size: var(--_op-text-pair-font-size-medium);
+    }
+
+    &.text-pair__title--large {
+      --__op-text-pair-title-font-size: var(--_op-text-pair-font-size-large);
+    }
+  }
+
+  .text-pair__subtitle {
+    font-size: var(--__op-text-pair-subtitle-font-size);
+    font-weight: var(--op-font-weight-normal);
+    line-height: var(--op-line-height-dense);
+
+    &.text-pair__subtitle--small {
+      --__op-text-pair-subtitle-font-size: var(--_op-text-pair-font-size-small);
+    }
+
+    &.text-pair__subtitle--medium {
+      --__op-text-pair-subtitle-font-size: var(--_op-text-pair-font-size-medium);
+    }
+
+    &.text-pair__subtitle--large {
+      --__op-text-pair-subtitle-font-size: var(--_op-text-pair-font-size-large);
+    }
+  }
+}
+
+.text-pair {
+  @extend %text-pair-global;
+}

src/stories/Components/Breadcrumbs/Breadcrumbs.js

@@ -1,11 +1,9 @@
 import { createIcon } from '../Icon/Icon'
 
-export const createBreadcrumbs = ({ size = '', separator = 'arrow_right', gap = 'default' }) => {
+export const createBreadcrumbs = ({ size = '', separator = 'arrow_right' }) => {
   const element = document.createElement('nav')
 
-  element.className = ['breadcrumbs', size === '' ? '' : `breadcrumbs--${size}`, gap === 'default' ? '' : gap]
-    .filter(Boolean)
-    .join(' ')
+  element.className = ['breadcrumbs', size === '' ? '' : `breadcrumbs--${size}`].filter(Boolean).join(' ')
 
   const links = [
     { type: 'link', text: 'USA' },

src/stories/Components/Breadcrumbs/Breadcrumbs.mdx

@@ -49,12 +49,6 @@ Breadcrumbs can be used as a standalone component, however, it does have a few d
 
 <Canvas of={BreadcrumbsStories.SeparatorIcon} />
 
-### Gap
-
-The [Gap Utilities](?path=/docs/utilities-gap--docs) can be used to increase the gap between each item with a default of `--op-space-x-small` if no gap is set.
-
-<Canvas of={BreadcrumbsStories.Gap} />
-
 ## Breadcrumb API
 
 Styles are built on css variables scoped to the breadcrumbs.

src/stories/Components/Breadcrumbs/Breadcrumbs.stories.js

@@ -11,10 +11,6 @@ export default {
       options: ['small', 'large'],
     },
     separator: { control: 'text' },
-    gap: {
-      control: { type: 'select' },
-      options: ['default', 'gap-xxs', 'gap-xl'],
-    },
   },
 }
 
@@ -39,9 +35,3 @@ export const SeparatorIcon = {
     separator: 'folder',
   },
 }
-
-export const Gap = {
-  args: {
-    gap: 'gap-xl',
-  },
-}

src/stories/Components/TextPair/TextPair.js

@@ -0,0 +1,31 @@
+export const createTextPair = ({
+  inline = false,
+  titleText = 'This is the Title',
+  titleSize = '',
+  subtitleText = 'This is the Subtitle',
+  subtitleSize = '',
+}) => {
+  const element = document.createElement('div')
+
+  element.className = ['text-pair', inline ? 'text-pair--inline' : ''].filter(Boolean).join(' ')
+
+  const title = document.createElement('span')
+  title.className = ['text-pair__title', titleSize === '' ? '' : `text-pair__title--${titleSize}`]
+    .filter(Boolean)
+    .join(' ')
+  title.innerText = titleText
+
+  const subtitle = document.createElement('span')
+  subtitle.className = ['text-pair__subtitle', subtitleSize === '' ? '' : `text-pair__subtitle--${subtitleSize}`]
+    .filter(Boolean)
+    .join(' ')
+  subtitle.innerText = subtitleText
+
+  element.append('\n  ')
+  element.appendChild(title)
+  element.append('\n  ')
+  element.appendChild(subtitle)
+  element.append('\n')
+
+  return element
+}

src/stories/Components/TextPair/TextPair.mdx

@@ -0,0 +1,112 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
+import * as TextPairStories from './TextPair.stories'
+
+import { createAlert } from '../Alert/Alert.js'
+
+<Meta of={TextPairStories} />
+
+# Text Pair
+
+The text pair component is used to display a title and subtitle together. It can also be used to group other elements within it, though should generally be reserved for text.
+
+## Playground
+
+<Canvas of={TextPairStories.Default} />
+<Controls of={TextPairStories.Default} />
+
+### Selective Imports
+
+Text Pair can be used as a standalone component, however, it does have a few dependencies. To see a full dependency list, see [Dependency Graph](?path=/docs/overview-selective-imports--docs#dependencies)
+
+```css
+// Depends on
+@import '@rolemodel/optics/dist/scss/core/tokens';
+@import '@rolemodel/optics/dist/scss/core/base';
+
+// Component
+@import '@rolemodel/optics/dist/scss/components/text_pair';
+```
+
+## Variations
+
+### Default
+
+`.text-pair` should be used on a div. Within it, `.text-pair__title` and `.text-pair__subtitle` on spans can be used to display the title and subtitle.
+
+<Canvas of={TextPairStories.Default} />
+
+### Inline
+
+`.text-pair--inline` can be added to display the title and subtitle horizontally aligned. This is useful for displaying a key, value pair.
+
+<Canvas of={TextPairStories.Inline} />
+
+### Title Size
+
+`.text-pair__title--small`, `.text-pair__title--medium`, `.text-pair__title--large`, (with medium being the default) modify the font size of the title text.
+
+<Canvas of={TextPairStories.TitleSize} />
+
+### Subtitle Size
+
+`.text-pair__subtitle--small`, `.text-pair__subtitle--medium`, `.text-pair__subtitle--large`, (with small being the default) modify the font size of the subtitle text.
+
+Description of subtitle size example
+
+<Canvas of={TextPairStories.SubtitleSize} />
+
+## Text Pair API
+
+Styles are built on css variables scoped to the text pair.
+
+Here are the variables that can be customized.
+
+{/* prettier-ignore-start */}
+```css
+--_op-text-pair-font-size-small:
+--_op-text-pair-font-size-medium:
+--_op-text-pair-font-size-large:
+```
+{/* prettier-ignore-end */}
+
+## Customizing Text Pair styles
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: createAlert({
+      title: 'Important!',
+      description: 'These patterns represent how to customize the style of the text pair for your project.',
+    }).outerHTML,
+  }}
+></div>
+
+The text pair classes are built on a [sass placeholder selector](https://sass-lang.com/documentation/style-rules/placeholder-selectors)
+
+This allows multiple classes to share the same behavior. You can modify all textpair behavior by overriding the `%text-pair-global` placeholder selector and setting any properties:
+
+```css
+%text-pair-global {
+  gap: var(--op-space-x-large);
+}
+```
+
+## New Text Pair Variations
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: createAlert({
+      title: 'Important!',
+      description: 'These patterns represent how to create new variations of the Text Pair for your project.',
+    }).outerHTML,
+  }}
+></div>
+
+Your application may need a custom text pair. To add one, just follow this template:
+
+```css
+.text-pair-{name} {
+  @extend %text-pair-global;
+
+  gap:
+}
+```

src/stories/Components/TextPair/TextPair.stories.js

@@ -0,0 +1,49 @@
+import { createTextPair } from './TextPair.js'
+
+export default {
+  title: 'Components/Text Pair',
+  render: ({ direction, ...args }) => {
+    return createTextPair({ direction, ...args })
+  },
+  argTypes: {
+    inline: { control: 'boolean' },
+    titleText: { control: 'text' },
+    titleSize: {
+      control: { type: 'select' },
+      options: ['small', 'medium', 'large'],
+    },
+    subtitleText: { control: 'text' },
+    subtitleSize: {
+      control: { type: 'select' },
+      options: ['small', 'medium', 'large'],
+    },
+  },
+}
+
+export const Default = {
+  args: {},
+}
+
+export const Inline = {
+  args: {
+    inline: true,
+    titleText: 'Temperature:',
+    subtitleText: '72℉',
+  },
+}
+
+export const TitleSize = {
+  args: {
+    inline: true,
+    titleText: 'Large Title',
+    titleSize: 'large',
+  },
+}
+
+export const SubtitleSize = {
+  args: {
+    inline: true,
+    subtitleText: 'Large Subtitle',
+    subtitleSize: 'large',
+  },
+}