[TR#8] Accordion (#178)

This PR adds an Accordion component built on the summary and details html elements.

.storybook/documentation.scss

@@ -23,6 +23,14 @@
   }
 }
 
+.transition-demo--accordion {
+  transition: var(--op-transition-accordion);
+
+  &:hover {
+    rotate: 0.25turn;
+  }
+}
+
 .transition-demo--input {
   transition: var(--op-transition-input);
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolemodel/optics",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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/accordion.scss

@@ -0,0 +1,38 @@
+%accordion-global {
+  // Public API (allowed to be overridden)
+  --_op-accordion-summary-min-height: calc(var(--op-space-2x-large) + var(--op-space-2x-small));
+
+  summary {
+    display: grid;
+    min-height: var(--_op-accordion-summary-min-height);
+    align-items: center;
+    cursor: pointer;
+    gap: var(--op-space-2x-small);
+    grid-template-columns: auto 1fr auto;
+
+    .accordion__label {
+      color: var(--op-color-neutral-on-plus-max);
+      font-size: var(--op-font-x-small);
+      font-weight: var(--op-font-weight-semi-bold);
+    }
+
+    .accordion__marker {
+      --op-mso-optical-sizing: 48;
+
+      font-size: var(--op-font-x-large);
+      justify-self: flex-end;
+      transition: var(--op-transition-accordion);
+      user-select: none;
+    }
+  }
+
+  &[open] {
+    summary .accordion__marker {
+      rotate: 0.25turn;
+    }
+  }
+}
+
+.accordion {
+  @extend %accordion-global;
+}

src/components/index.scss

@@ -1,3 +1,4 @@
+@import 'accordion';
 @import 'alert';
 @import 'avatar';
 @import 'badge';

src/core/tokens/base_tokens.scss

@@ -176,6 +176,7 @@
   /**
   * @tokens Transition
   */
+  --op-transition-accordion: rotate 120ms ease-in;
   --op-transition-input: all 120ms ease-in;
   --op-transition-sidebar: all 200ms ease-in-out;
   --op-transition-modal: all 300ms ease-in;

src/stories/Components/Accordion/Accordion.js

@@ -0,0 +1,43 @@
+import { createIcon } from '../Icon/Icon'
+
+export const createAccordion = ({
+  headerLabel = 'Header Label',
+  marker = 'arrow_right',
+  additionalHeaderContent = '',
+  flipHeaderAndMarker = false,
+  content = 'Something small enough to escape casual notice.',
+}) => {
+  const element = document.createElement('details')
+  element.className = 'accordion'
+
+  const summary = document.createElement('summary')
+
+  const label = document.createElement('span')
+  label.className = 'accordion__label'
+  label.innerHTML = headerLabel
+
+  const markerIcon = createIcon({ name: marker })
+  markerIcon.className += ' accordion__marker'
+
+  summary.innerHTML = '\n    '
+  if (flipHeaderAndMarker) {
+    summary.innerHTML += label.outerHTML
+    summary.innerHTML += '\n    '
+    summary.innerHTML += markerIcon.outerHTML
+  } else {
+    summary.innerHTML += markerIcon.outerHTML
+    summary.innerHTML += '\n    '
+    summary.innerHTML += label.outerHTML
+  }
+  summary.innerHTML += '\n    '
+  summary.innerHTML += additionalHeaderContent
+  summary.innerHTML += '\n  '
+
+  element.innerHTML = '\n  '
+  element.innerHTML += summary.outerHTML
+  element.innerHTML += '\n  '
+  element.innerHTML += content
+  element.innerHTML += '\n'
+
+  return element
+}

src/stories/Components/Accordion/Accordion.mdx

@@ -0,0 +1,73 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
+import * as AccordionStories from './Accordion.stories'
+
+<Meta of={AccordionStories} />
+
+# Accordion
+
+Accordion classes are built on the `details` and `summary` html elements. They provide consistent and composable styling for disclosure widgets.
+
+## Playground
+
+<Canvas of={AccordionStories.Default} />
+<Controls of={AccordionStories.Default} />
+
+### Selective Imports
+
+Accordion 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';
+@import '@rolemodel/optics/dist/scss/components/icon';
+
+// Component
+@import '@rolemodel/optics/dist/scss/components/accordion';
+```
+
+## Variations
+
+### Default
+
+`.accordion` used on a `details` element with a `summary` element as the first child will create an accordion component.
+Within the `summary`, a span with the class `accordion__label` will be used as the title of the accordion and `accordion__marker` will be used as the icon.
+
+Other content can be placed within the summary, but the `accordion__label` and `accordion__marker` classes must be used for the accordion to work properly.
+
+<Canvas of={AccordionStories.Default} />
+
+### Swapped Label and Marker
+
+Positioning the marker after the label inside of the summary will result in the marker being on the right side of the accordion.
+
+<Canvas of={AccordionStories.FlipHeaderAndMarker} />
+
+### Additional Header Content
+
+Additional content can be included within the `summary` element in any order. Anything not within the `.accordion__label` or `.accordion__marker` classes will be rendered wherever you place it in the `summary`. Note: Content placed between the label and the marker will fill the width between them. If placing a button there, you may want to wrap it in a div so the button doesn't stretch the whole space.
+
+<Canvas of={AccordionStories.AdditionalHeaderContent} />
+
+## Overriding styles
+
+The accordion 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 accordion behavior by overriding the `%accordion-global` placeholder selector and setting any properties:
+
+```css
+%accordion-global {
+}
+```
+
+## Custom Accordion
+
+Your application may need a custom accordion. To add one, just follow this template:
+
+```css
+.accordion-{name} {
+  @extend %accordion-global;
+
+  --_op-accordion-summary-min-height: var(--op-font-small);
+}
+```

src/stories/Components/Accordion/Accordion.stories.js

@@ -0,0 +1,35 @@
+import { createAccordion } from './Accordion.js'
+import { createButton } from '../Button/Button.js'
+
+export default {
+  title: 'Components/Accordion',
+  render: ({ option1, ...args }) => {
+    return createAccordion({ option1, ...args })
+  },
+  argTypes: {
+    headerLabel: { control: 'text' },
+    marker: { control: 'text' },
+    additionalHeaderContent: { control: 'text' },
+    flipHeaderAndMarker: { control: 'boolean' },
+    content: { control: 'text' },
+  },
+  parameters: {
+    layout: 'padded',
+  },
+}
+
+export const Default = {
+  args: {},
+}
+
+export const FlipHeaderAndMarker = {
+  args: {
+    flipHeaderAndMarker: true,
+  },
+}
+
+export const AdditionalHeaderContent = {
+  args: {
+    additionalHeaderContent: createButton({ label: 'Button' }).outerHTML,
+  },
+}