@orangesk/orange-design-system 2.0.0-alpha.1 → 2.0.0-alpha.3

package/src/components/BlockAction/BlockAction.mdx

@@ -0,0 +1,244 @@
+import { useRef, useEffect } from 'react';
+import { ComponentDocs, DocsTable } from '@lighting-beetle/lighter-styleguide';
+import { Preview } from '../../styleguide/';
+
+import { useStatic } from '../../utils/hooks';
+import Toggle from '../../scripts/modules/Toggle';
+import Accordion, { AccordionItem } from '../Accordion';
+import Bar, { BarItem } from '../Bar';
+import Button from '../Button';
+import Card, { CardSection } from '../Card';
+import Icon from '../Icon';
+import Link from '../Link';
+import BlockAction, {
+  BlockActionControl,
+  BlockActionOverride,
+  BlockActionIndicator,
+} from './';
+
+export const ToggleButton = props => {
+  let [buttonRef] = useStatic(Toggle);
+  return <button ref={buttonRef} {...props} />;
+};
+
+# BlockAction
+
+Utility component that makes whole blocks clickable.
+
+Although it is possible to wrap even complex layouts in an `<a />` and even use flexbox layout in `<button />`s, this results in verbose screenreader output. BlockAction solves this issue and even allows for an override - a separate clickable element inside a clickable block, and an indicator - a non-interactive element that can indicate the block action is being hovered.
+
+## Anatomy
+
+BlockAction is a utility component. It does not render any elements. It's sole purpose is to assign classNames to it's children components/elements.
+
+- **BlockAction** / `.block-action`<br />
+  Wrapper around the whole clickable block. Enables positioning.
+  - **BlockActionControl** / `.block-action__control`<br />
+    Interactive element (button or anchor) that receives a click event fired anywhere inside BlockAction. It has a pseudo element that spans the whole BlockAction wrapper. **Only one** control element allowed per BlockAction.
+  - **BlockActionOverride** / `.block-action__override`<br />
+    Another interactive element that can be clicked without firing a click event on BlockActionControl. This is achieved by it's own stacking context. BlockAction can contain multiple overrides (max. 2 recommended).
+  - **BlockActionIndicator** / `.block-action__indicator`<br />
+    Shows basic hover styles, indicates that the control element is heing hovered. Usually an [Icon](/components/icon).
+
+## Examples
+
+### Card
+
+The following example shows a BlockAction [Card](/components/card). It's Control element is a [Link](/components/link) inside a heading. When hovering over the Card, the cursor changes to pointer and the Link element enters it's hover state. This is done via a pseudo element that spans the whole BlockAction wrapper. The Override element can be interated with separately as it has it's own staciking context. Clicking it does not activate the Control element.
+
+<Preview>
+  <BlockAction>
+    <Card hasBorder>
+      <CardSection>
+        <h2 hasMdxLink={false}>
+          <Bar tag="span">
+            <BarItem isFilling tag="span">
+              <BlockActionControl>
+                <Link href="#">Control anchor</Link>
+              </BlockActionControl>
+            </BarItem>
+            <BarItem tag="span">
+              <BlockActionIndicator>
+                <Icon name="chevron-right" size="medium" />
+              </BlockActionIndicator>
+            </BarItem>
+          </Bar>
+        </h2>
+        <p>Aenean lacinia bibendum nulla sed consectetur.</p>
+        <BlockActionOverride>
+          <Button>Override button</Button>
+        </BlockActionOverride>
+      </CardSection>
+    </Card>
+  </BlockAction>
+</Preview>
+
+### Accordion
+
+The following example shows an [Accordion](/components/accordion) with a [Button](/components/button) performing a separate action. It's Control element is an accordion button, which serves for opening and closing the accordion item and is placed inside a [Bar](/components/bar) layout. Since the accordion icon sits outsite the accordion button to make room for the override button, it's active class must be manually controlled using [Toggle](/js-modules/toggle) via `[data-toggle]` attribute. The icon is also being used as an Indicator element which changes the icon color when the Control element is being hovered.
+
+<Preview>
+  <Accordion>
+    {[1, 2, 3].map(item => (
+      <AccordionItem
+        key={item.toString()}
+        title={`Block action accordion ${item}`}
+        renderHeader={(title, id) => (
+          <BlockAction>
+            <Bar canWrap={false} className="accordion__header">
+              <BarItem isFilling>
+                <h3 className="accordion__header" hasMdxLink={false}>
+                  <BlockActionControl>
+                    <ToggleButton
+                      type="button"
+                      aria-expanded="false"
+                      className={`accordion__button`}
+                      aria-controls={`${id}-section`}
+                      id={id}
+                      data-accordion-toggle
+                      data-toggle={JSON.stringify([
+                        {
+                          target: `#manual-accordion-icon-${item}`,
+                          attribute: 'class',
+                          value: 'is-active',
+                        },
+                      ])}
+                    >
+                      <span className="accordion__title">{title}</span>
+                    </ToggleButton>
+                  </BlockActionControl>
+                </h3>
+              </BarItem>
+              <BarItem>
+                <BlockActionOverride>
+                  <Button size="small">Override {item}</Button>
+                </BlockActionOverride>
+              </BarItem>
+              <BarItem>
+                <BlockActionIndicator>
+                  <Icon
+                    id={`manual-accordion-icon-${item}`}
+                    className={`accordion__icon`}
+                    name="chevron-down"
+                    size="medium"
+                  />
+                </BlockActionIndicator>
+              </BarItem>
+            </Bar>
+          </BlockAction>
+        )}
+      >
+        <p>
+          Cum sociis natoque penatibus et magnis dis parturient montes, nascetur
+          ridiculus mus. Curabitur blandit tempus porttitor.
+        </p>
+      </AccordionItem>
+    ))}
+  </Accordion>
+</Preview>
+
+### Color reset
+
+Use class `.block-action__indicator--color-reset` if you don't want text color change when BlockAction is being hovered.
+
+<Preview>
+  <BlockAction>
+    <BlockActionIndicator className="block-action__indicator--color-reset">
+      <div className="card border border--gray border-radius--medium">
+        <div className="card__section">
+          <BlockActionControl>
+            <Button>Control</Button>
+          </BlockActionControl>
+          <p>With class .block-action__indicator--color-reset</p>
+        </div>
+      </div>
+    </BlockActionIndicator>
+  </BlockAction>
+</Preview>
+
+## JS module reference
+
+Javascript is required when using an Indicator element.
+
+All elements with `[data-block-action]` attribute are initialized automatically.
+
+When a Block action contains a control and at least one indicator, the JS module adds mouseenter and mouseleave listeners to the control element and manages toggling a classname on the indicator elements.
+
+### Custom init
+
+```js
+const instance = new window.ODS.modules.BlockAction(
+  document.getElementByUd('my-block-action'),
+  config
+);
+```
+
+### Config
+
+<DocsTable
+  data={[
+    {
+      prop: 'controlSelector',
+      type: 'string',
+      default: '.block-action__control',
+      description: 'Selector for looking up the control element',
+    },
+    {
+      prop: 'indicatorSelector',
+      type: 'string',
+      default: '.block-action__indicator',
+      description: 'Selector for looking up indicator element(s).',
+    },
+    {
+      prop: 'activeClass',
+      type: 'string',
+      default: 'is-indicating',
+      description:
+        'CSS class name toggled on indicator elements(s) when the control element is being hovered.',
+    },
+  ]}
+/>
+
+### Methods
+
+```js
+const instance = document.querySelector(elementSelector).ODS_BlockAction;
+instance.method();
+```
+
+<DocsTable
+  data={[
+    {
+      prop: 'init',
+      type: 'func',
+      default: '() => {}',
+      description:
+        'Initialize an instance. Called automatically on `new BlockAction(el, config)`',
+    },
+    {
+      prop: 'destroy',
+      type: 'func',
+      default: '() => {}',
+      description: 'Destroy the instance - removes all listeners',
+    },
+    {
+      prop: 'update',
+      type: 'func',
+      default: '() => {}',
+      description: 'Destroys the instance and calls a fresh init().',
+    },
+  ]}
+/>
+
+## Props
+
+All components clone their children and assign them the required classNames.
+
+<ComponentDocs component={BlockAction} />
+<ComponentDocs component={BlockActionControl} />
+<ComponentDocs component={BlockActionIndicator} />
+<ComponentDocs component={BlockActionOverride} />
+
+## Notes
+
+Based on [Inclusive Components - Cards](https://inclusive-components.design/cards/)

package/src/components/BlockAction/BlockAction.static.ts

@@ -0,0 +1,104 @@
+export interface BlockActionConfig {
+  controlSelector: string;
+  indicatorSelector: string;
+  activeClass: string;
+}
+
+export const defaultConfig: BlockActionConfig = {
+  controlSelector: ".block-action__control",
+  indicatorSelector: ".block-action__indicator",
+  activeClass: "is-indicating",
+};
+
+export default class BlockAction {
+  private element: HTMLElement;
+  private config: BlockActionConfig;
+  private controlElement: HTMLElement | null = null;
+  private indicatorElements: HTMLElement[] = [];
+
+  constructor(element: HTMLElement, config?: Partial<BlockActionConfig>) {
+    this.element = element;
+    this.config = { ...defaultConfig, ...config };
+
+    this.highlightIndicators = this.highlightIndicators.bind(this);
+    this.unhighlightIndicators = this.unhighlightIndicators.bind(this);
+
+    (this.element as any).ODS_BlockAction = this;
+
+    this.init();
+    return this;
+  }
+
+  private init(): void {
+    this.controlElement = this.element.querySelector(
+      this.config.controlSelector,
+    ) as HTMLElement | null;
+    this.indicatorElements = Array.from(
+      this.element.querySelectorAll(this.config.indicatorSelector),
+    ) as HTMLElement[];
+
+    if (!this.controlElement || this.indicatorElements.length < 1) {
+      return;
+    }
+
+    this.controlElement.addEventListener(
+      "mouseenter",
+      this.highlightIndicators,
+    );
+    this.controlElement.addEventListener(
+      "mouseleave",
+      this.unhighlightIndicators,
+    );
+    this.controlElement.addEventListener("focus", this.highlightIndicators);
+    this.controlElement.addEventListener("blur", this.unhighlightIndicators);
+  }
+
+  private highlightIndicators(): void {
+    this.indicatorElements.forEach((el) =>
+      el.classList.add(this.config.activeClass),
+    );
+  }
+
+  private unhighlightIndicators(): void {
+    this.indicatorElements.forEach((el) =>
+      el.classList.remove(this.config.activeClass),
+    );
+  }
+
+  public destroy(): void {
+    this.indicatorElements.forEach((el) =>
+      el.classList.remove(this.config.activeClass),
+    );
+    if (this.controlElement) {
+      this.controlElement.removeEventListener(
+        "mouseenter",
+        this.highlightIndicators,
+      );
+      this.controlElement.removeEventListener(
+        "mouseleave",
+        this.unhighlightIndicators,
+      );
+      this.controlElement.removeEventListener(
+        "focus",
+        this.highlightIndicators,
+      );
+      this.controlElement.removeEventListener(
+        "blur",
+        this.unhighlightIndicators,
+      );
+    }
+    this.controlElement = null;
+    this.indicatorElements = [];
+  }
+
+  public update(): void {
+    this.destroy();
+    this.init();
+  }
+
+  static getInstance(el: HTMLElement): BlockAction | null {
+    return el && (el as any).ODS_BlockAction
+      ? (el as any).ODS_BlockAction
+      : null;
+  }
+}

package/src/components/BlockAction/BlockAction.tsx

@@ -0,0 +1,27 @@
+import React, { ReactElement } from "react";
+
+import { CloneElementWithClassName } from "./CloneElementWithClassName";
+import { Provider } from "./Context";
+
+export interface BlockActionProps {
+  /** 1 and only one single element */
+  children: ReactElement;
+  className?: string;
+  [key: string]: any;
+}
+
+const BlockAction: React.FC<BlockActionProps> = (props) => {
+  return (
+    <Provider>
+      <CloneElementWithClassName
+        {...props}
+        className="block-action"
+        data-block-action
+      />
+    </Provider>
+  );
+};
+
+BlockAction.displayName = "BlockAction";
+
+export { BlockAction };

package/src/components/BlockAction/BlockActionControl.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import React, { useContext, ReactElement } from "react";
+
+import { Context } from "./Context";
+import { CloneElementWithClassName } from "./CloneElementWithClassName";
+
+export interface BlockActionControlProps {
+  /** 1 and only one single element */
+  children: ReactElement;
+  className?: string;
+  [key: string]: any;
+}
+
+const BlockActionControl: React.FC<BlockActionControlProps> = (props) => {
+  const { isActive, setIsActive, setIsIndicating } = useContext(Context);
+  return (
+    <CloneElementWithClassName
+      {...props}
+      className="block-action__control"
+      onMouseEnter={() => setIsIndicating(true)}
+      onMouseLeave={() => setIsIndicating(false)}
+      onFocus={() => setIsIndicating(true)}
+      onBlur={() => setIsIndicating(false)}
+      onClick={() => setIsActive(!isActive)}
+    />
+  );
+};
+
+BlockActionControl.displayName = "BlockActionControl";
+
+export { BlockActionControl };

package/src/components/BlockAction/BlockActionIndicator.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import React, { useContext, ReactElement } from "react";
+import cx from "classnames";
+
+import { Context } from "./Context";
+import { CloneElementWithClassName } from "./CloneElementWithClassName";
+
+export interface BlockActionIndicatorProps {
+  /** 1 and only one single element */
+  children: ReactElement;
+  className?: string;
+  [key: string]: any;
+}
+
+const BlockActionIndicator: React.FC<BlockActionIndicatorProps> = (props) => {
+  const { isActive, isIndicating } = useContext(Context);
+
+  return (
+    <CloneElementWithClassName
+      {...props}
+      className={cx("block-action__indicator", props.className, {
+        "is-indicating": isIndicating,
+        "is-active": isActive,
+      })}
+    />
+  );
+};
+
+BlockActionIndicator.displayName = "BlockActionIndicator";
+
+export { BlockActionIndicator };

package/src/components/BlockAction/CloneElementWithClassName.tsx

@@ -0,0 +1,23 @@
+import React, { ReactElement } from "react";
+import cx from "classnames";
+
+interface CloneElementWithClassNameProps {
+  className?: string;
+  children: ReactElement<any>;
+  [key: string]: any;
+}
+
+const CloneElementWithClassName: React.FC<CloneElementWithClassNameProps> = ({
+  className,
+  children,
+  ...other
+}) =>
+  React.cloneElement(children, {
+    ...(typeof children.props === "object" && children.props !== null
+      ? children.props
+      : {}),
+    ...other,
+    className: cx(children.props && children.props.className, className),
+  });
+
+export { CloneElementWithClassName };

package/src/components/BlockAction/Context.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import React, { useState, ReactNode, Dispatch, SetStateAction } from "react";
+
+interface ContextType {
+  isIndicating: boolean;
+  isActive: boolean;
+  setIsActive: Dispatch<SetStateAction<boolean>>;
+  setIsIndicating: Dispatch<SetStateAction<boolean>>;
+}
+
+export const Context = React.createContext<ContextType>({
+  isIndicating: false,
+  isActive: false,
+  setIsActive: () => {},
+  setIsIndicating: () => {},
+});
+
+interface ProviderProps {
+  children: ReactNode;
+}
+
+export const Provider: React.FC<ProviderProps> = (props) => {
+  const [isIndicating, setIsIndicating] = useState(false);
+  const [isActive, setIsActive] = useState(false);
+
+  return (
+    <Context.Provider
+      value={{
+        isIndicating,
+        setIsIndicating,
+        isActive,
+        setIsActive,
+      }}
+    >
+      {props.children}
+    </Context.Provider>
+  );
+};

package/src/components/BlockAction/index.tsx

@@ -0,0 +1,29 @@
+import React, { ReactElement } from "react";
+
+import { CloneElementWithClassName } from "./CloneElementWithClassName";
+import { BlockAction } from "./BlockAction";
+import { BlockActionControl } from "./BlockActionControl";
+import { BlockActionIndicator } from "./BlockActionIndicator";
+
+import "./styles/style.scss";
+
+export interface BlockActionOverrideProps {
+  /** 1 and only one single element */
+  children: ReactElement;
+  className?: string;
+  [key: string]: any;
+}
+
+export { BlockAction };
+
+export { BlockActionControl };
+
+const BlockActionOverride: React.FC<BlockActionOverrideProps> = (props) => (
+  <CloneElementWithClassName {...props} className="block-action__override" />
+);
+
+BlockActionOverride.displayName = "BlockActionOverride";
+
+export { BlockActionOverride };
+
+export { BlockActionIndicator };

package/src/components/BlockAction/styles/config.scss

@@ -0,0 +1,10 @@
+@use '../../../styles/tokens/color';
+
+/// Generates indicator hover colors. Each key is a background color and matching hover color.
+/// @type Map
+$indicator-colors: (
+  'default': color.$orange-dark,
+  'black': color.$orange,
+  'orange': color.$white,
+  'orange-dark': color.$black,
+)

package/src/components/BlockAction/styles/mixins.scss

@@ -0,0 +1,33 @@
+@use "sass:map";
+@use "./config";
+
+@mixin layout-base {
+  position: relative;
+
+  &:focus-within,
+  &:hover {
+    outline: 2px solid var(--color-border-accent);
+    outline-offset: 1px;
+  }
+}
+
+@mixin control {
+  &::before {
+    content: "";
+    position: absolute;
+    z-index: 1;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+  }
+}
+
+@mixin override {
+  position: relative;
+  z-index: 1;
+}
+
+@mixin indicator($bg-color: "default", $config: config.$indicator-colors) {
+  color: map.get($config, $bg-color);
+}

package/src/components/BlockAction/styles/style.scss

@@ -0,0 +1,35 @@
+@use "./mixins";
+
+@layer components {
+  .block-action {
+    @include mixins.layout-base;
+
+    &__control {
+      @include mixins.control;
+    }
+
+    &__override {
+      @include mixins.override;
+    }
+
+    &__indicator.is-indicating:not(.block-action__indicator--color-reset) {
+      @include mixins.indicator;
+
+      .bg-white & {
+        @include mixins.indicator;
+      }
+
+      .bg-black & {
+        @include mixins.indicator("black");
+      }
+
+      .bg-orange & {
+        @include mixins.indicator("orange");
+      }
+
+      .bg-orange-dark & {
+        @include mixins.indicator("orange-dark");
+      }
+    }
+  }
+}