@marigold/system 0.1.0 → 0.2.0

package/src/Element.test.tsx

@@ -0,0 +1,203 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { useStyles } from './useStyles';
+import { ThemeProvider } from './useTheme';
+import { Element } from './Element';
+
+const theme = {
+  text: {
+    body: {
+      fontSize: 1,
+      color: 'black',
+      marginTop: '2px',
+    },
+    heading: {
+      fontSize: 3,
+      color: 'primary',
+    },
+    padding: {
+      paddingTop: '2px',
+    },
+  },
+};
+
+test('renders a <div> by default', () => {
+  render(<Element>Text</Element>);
+  const testelem = screen.getByText('Text');
+
+  expect(testelem instanceof HTMLDivElement).toBeTruthy();
+});
+
+test('supports as prop', () => {
+  render(<Element as="p">Text</Element>);
+  const testelem = screen.getByText('Text');
+
+  expect(testelem instanceof HTMLParagraphElement).toBeTruthy();
+});
+
+test('supports HTML className attribute', () => {
+  render(<Element className="my-custom-class">Text</Element>);
+  const element = screen.getByText('Text');
+
+  expect(element.getAttribute('class')).toMatch('my-custom-class');
+});
+
+test('passes down HTML attributes', () => {
+  render(
+    <Element className="my-custom-class" id="element-id" disabled>
+      Text
+    </Element>
+  );
+  const element = screen.getByText('Text');
+
+  expect(element.getAttribute('id')).toEqual('element-id');
+  expect(element.getAttribute('disabled')).toMatch('');
+  expect(element.getAttribute('class')).toMatch('my-custom-class');
+});
+
+test('forwards ref', () => {
+  const ref = React.createRef<HTMLButtonElement>();
+  render(
+    <Element as="button" ref={ref}>
+      button
+    </Element>
+  );
+
+  expect(ref.current instanceof HTMLButtonElement).toBeTruthy();
+});
+
+test('base styles first', () => {
+  const { getByText } = render(<Element as="p">Text</Element>);
+  const testelem = getByText('Text');
+  const style = getComputedStyle(testelem);
+
+  expect(style.marginTop).toEqual('0px'); // 0px come from base
+});
+
+test('variant styles second', () => {
+  const TestComponent: React.FC<{ variant?: 'body' }> = ({
+    variant = 'body',
+    children,
+    ...props
+  }) => {
+    return (
+      <Element as="p" variant={`text.${variant}`} {...props}>
+        {children}
+      </Element>
+    );
+  };
+
+  const { getByText } = render(
+    <ThemeProvider theme={theme}>
+      <TestComponent>Text</TestComponent>
+    </ThemeProvider>
+  );
+  const testelem = getByText('Text');
+  const style = getComputedStyle(testelem);
+
+  expect(style.marginTop).not.toEqual('0px'); // 0px come from base
+  expect(style.marginBottom).toEqual('0px'); // 0px still come from base
+  expect(style.marginTop).toEqual('2px'); // 2px come from variant
+});
+
+test('array of variant styles', () => {
+  const TestComponent: React.FC<{ variant?: 'body' }> = ({
+    variant = 'body',
+    children,
+    ...props
+  }) => {
+    return (
+      <Element as="p" variant={[`text.${variant}`, `text.padding`]} {...props}>
+        {children}
+      </Element>
+    );
+  };
+
+  const { getByText } = render(
+    <ThemeProvider theme={theme}>
+      <TestComponent>Text</TestComponent>
+    </ThemeProvider>
+  );
+  const testelem = getByText('Text');
+  const style = getComputedStyle(testelem);
+
+  expect(style.marginTop).not.toEqual('0px'); // 0px come from base
+  expect(style.marginBottom).toEqual('0px'); // 0px still come from base
+  expect(style.marginTop).toEqual('2px'); // 2px marginTop come from variant
+  expect(style.paddingTop).toEqual('2px'); // 2px paddingTop come from variant
+});
+
+test('custom styles with css prop third', () => {
+  const TestComponent: React.FC<{ variant?: 'body' }> = ({
+    variant = 'body',
+    children,
+    ...props
+  }) => {
+    return (
+      <Element
+        as="p"
+        variant={`text.${variant}`}
+        css={{ marginTop: '4px' }}
+        {...props}
+      >
+        {children}
+      </Element>
+    );
+  };
+
+  const { getByText } = render(
+    <ThemeProvider theme={theme}>
+      <TestComponent>Text</TestComponent>
+    </ThemeProvider>
+  );
+  const testelem = getByText('Text');
+  const style = getComputedStyle(testelem);
+
+  expect(style.marginTop).not.toEqual('0px'); // do not apply 0px from base
+  expect(style.marginTop).not.toEqual('2px'); // do not apply 2px from variant
+  expect(style.marginTop).toEqual('4px'); // apply 4px from custom styles
+});
+
+test("don't apply the same reset multiple times", () => {
+  const Button = ({ className }: { className?: string }) => {
+    const classNames = useStyles({ element: 'button', className });
+    return (
+      <Element as="button" title="button" className={classNames}>
+        Click me!
+      </Element>
+    );
+  };
+  const Wrapper = () => <Button />;
+
+  render(<Wrapper />);
+  const button = screen.getByTitle('button');
+  const classNames = button.className.split(' ').filter(i => i.length);
+
+  // Test if applied classnames are unique
+  expect(classNames.length).toEqual([...new Set(classNames)].length);
+});
+
+test('normalize tag name <a>', () => {
+  const TestComponent: React.FC<{ variant?: 'body' }> = ({
+    variant = 'body',
+    children,
+    ...props
+  }) => {
+    return (
+      <Element as="a" variant={`text.${variant}`} {...props}>
+        {children}
+      </Element>
+    );
+  };
+
+  const { getByText } = render(
+    <ThemeProvider theme={theme}>
+      <TestComponent>Link</TestComponent>
+    </ThemeProvider>
+  );
+  const testelem = getByText('Link');
+  const style = getComputedStyle(testelem);
+
+  expect(style.boxSizing).toEqual('border-box'); // from base
+  expect(style.textDecoration).toEqual('none'); // from a
+});

package/src/Element.tsx

@@ -0,0 +1,59 @@
+import { jsx } from '@emotion/react';
+import { forwardRef } from 'react';
+import {
+  PolymorphicPropsWithRef,
+  PolymorphicComponentWithRef,
+} from '@marigold/types';
+
+import { getNormalizedStyles } from './normalize';
+import { CSSObject } from './types';
+import { useTheme } from './useTheme';
+
+export type ElementOwnProps = {
+  css?: CSSObject;
+  variant?: string | string[];
+};
+
+export type ElementProps = PolymorphicPropsWithRef<ElementOwnProps, 'div'>;
+
+/**
+ * Function expression to check if there is any falsy value or empty object
+ */
+const isNotEmpty = (val: any) =>
+  !(val && Object.keys(val).length === 0 && val.constructor === Object);
+
+/**
+ * Get the normalized base styles
+ */
+const baseStyles = getNormalizedStyles('base');
+
+export const Element: PolymorphicComponentWithRef<ElementOwnProps, 'div'> =
+  forwardRef(
+    ({ as = 'div', css: styles = {}, variant, children, ...props }, ref) => {
+      const { css } = useTheme();
+
+      /**
+       * Transform variant input for `@theme-ui/css`
+       */
+      const variants = Array.isArray(variant)
+        ? variant.map(v => ({ variant: v }))
+        : [{ variant }];
+
+      return jsx(
+        as,
+        {
+          ...props,
+          ...{
+            css: [
+              baseStyles,
+              getNormalizedStyles(as),
+              ...variants.map(v => css(v)),
+              css(styles),
+            ].filter(isNotEmpty),
+          },
+          ref,
+        },
+        children
+      );
+    }
+  );

package/src/concepts-principles.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks';
+import { Meta } from '@storybook/addon-docs';
 
 <Meta title="Guides/Concepts & Principles" />
 

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './Element';
 export * from './cache';
 export * from './types';
 export * from './useClassname';

package/src/normalize.test.tsx

@@ -0,0 +1,42 @@
+import { getNormalizedStyles } from './normalize';
+
+test('get base styles', () => {
+  const baseStyles = getNormalizedStyles('base');
+  expect(baseStyles).toEqual({
+    boxSizing: 'border-box',
+    margin: 0,
+    padding: 0,
+    minWidth: 0,
+    fontSize: '100%',
+    fontFamily: 'inherit',
+    verticalAlign: 'baseline',
+    WebkitTapHighlightColor: 'transparent',
+  });
+});
+
+test('get reset style by element', () => {
+  const baseStyles = getNormalizedStyles('a');
+  expect(baseStyles).toEqual({
+    textDecoration: 'none',
+    touchAction: 'manipulation',
+  });
+});
+
+test('getNormalizedStyles returns base if input is not a string', () => {
+  const baseStyles = getNormalizedStyles(undefined);
+  expect(baseStyles).toEqual({
+    boxSizing: 'border-box',
+    margin: 0,
+    padding: 0,
+    minWidth: 0,
+    fontSize: '100%',
+    fontFamily: 'inherit',
+    verticalAlign: 'baseline',
+    WebkitTapHighlightColor: 'transparent',
+  });
+});
+
+test('getNormalizedStyles returns empty object if input is unknown', () => {
+  const baseStyles = getNormalizedStyles('p');
+  expect(baseStyles).toEqual({});
+});

package/src/normalize.ts

@@ -0,0 +1,131 @@
+import { ElementType } from 'react';
+
+const base = {
+  boxSizing: 'border-box',
+  margin: 0,
+  padding: 0,
+  minWidth: 0,
+  fontSize: '100%',
+  fontFamily: 'inherit',
+  verticalAlign: 'baseline',
+  WebkitTapHighlightColor: 'transparent',
+} as const;
+
+// Content
+// ---------------
+const block = {
+  display: 'block',
+} as const;
+
+const list = {
+  // empty
+} as const;
+
+const table = {
+  borderCollapse: 'collapse',
+  borderSpacing: 0,
+} as const;
+
+// Typography
+// ---------------
+const a = {
+  textDecoration: 'none',
+  touchAction: 'manipulation',
+} as const;
+
+const quote = {
+  quotes: 'none',
+  selectors: {
+    '&:before, &:after': {
+      content: "''",
+    },
+  },
+} as const;
+
+// Form Elements
+// ---------------
+const button = {
+  display: 'block',
+  appearance: 'none',
+  background: 'transparent',
+  textAlign: 'center',
+  touchAction: 'manipulation',
+} as const;
+
+const input = {
+  display: 'block',
+  appearance: 'none',
+  selectors: {
+    '&::-ms-clear': {
+      display: 'none',
+    },
+    '&::-webkit-search-cancel-button': {
+      WebkitAppearance: 'none',
+    },
+  },
+} as const;
+
+const select = {
+  display: 'block',
+  appearance: 'none',
+  selectors: {
+    '&::-ms-expand': {
+      display: 'none',
+    },
+  },
+} as const;
+
+const textarea = {
+  display: 'block',
+  appearance: 'none',
+} as const;
+
+// Reset
+// ---------------
+const reset = {
+  article: block,
+  aside: block,
+  details: block,
+  figcaption: block,
+  figure: block,
+  footer: block,
+  header: block,
+  hgroup: block,
+  menu: block,
+  nav: block,
+  section: block,
+  ul: list,
+  ol: list,
+  blockquote: quote,
+  q: quote,
+  a,
+  base,
+  table,
+  select,
+  button,
+  textarea,
+  input,
+} as const;
+
+export type NormalizedElement = keyof typeof reset;
+const isKnownElement = (input: string): input is NormalizedElement =>
+  input in reset;
+
+/**
+ * Helper to conveniently get reset styles.
+ */
+export const getNormalizedStyles = (input?: ElementType): object => {
+  /**
+   * If a React component is given, we don't apply any reset styles
+   * and return the base reset.
+   */
+  if (typeof input !== 'string') {
+    return reset.base;
+  }
+
+  /**
+   * Try to find the reset style for a HTML element. If the element
+   * is not included return empty styles.
+   */
+  return isKnownElement(input) ? reset[input] : {};
+};

package/src/reset.ts

@@ -18,7 +18,7 @@ const block = css({
 });
 
 const list = css({
-  listStyle: 'none',
+  // empty
 });
 
 const table = css({
@@ -30,7 +30,7 @@ const table = css({
 // ---------------
 const a = css({
   textDecoration: 'none',
-  touchAction: 'manipulation'
+  touchAction: 'manipulation',
 });
 
 const quote = css({
@@ -49,7 +49,7 @@ const button = css({
   appearance: 'none',
   background: 'transparent',
   textAlign: 'center',
-  touchAction: 'manipulation'
+  touchAction: 'manipulation',
 });
 
 const input = css({

package/src/useStyles.stories.mdx

@@ -0,0 +1,24 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs';
+import { useStyles } from './useStyles';
+import { Text } from '@marigold/components';
+
+<Meta title="Hooks/useStyles" />
+
+# useStyles
+
+<Canvas>
+  <Story name="usestyles">
+    <Text>
+      The useStyles hook generates classnames that style your component:
+    </Text>
+  </Story>
+</Canvas>
+
+```tsx
+useStyles({
+    element: ElementType; // reset styles for the given HTML element
+    css: CSSObject; // custom styles
+    variant: string|string[]; // theme variant(s)
+    className: string; // additional classnames
+})
+```

package/src/writeComponent.stories.mdx

@@ -1,126 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks';
-
-<Meta title="Guides/How to Write and Use Components" />
-
-# How to Write and Use Components
-
-Small guidance for creating components in Marigold.
-
-## API
-
-### Use the base HTML element
-
-Create your basic component by using the HTML tagname with its own props. Specify the HTML element you want to render.
-The `system` helper infers a forwardRef (and will soon be abolished).
-
-```tsx
-export const Button = system<ButtonProps, 'button'>(({ ...props }) => {
-  return <button {...props}>{children}</button>;
-});
-```
-
-### Add Styling via Classnames
-
-In order to add styles to your component, you can work with classNames. ClassNames are automatically generated via the `useStyles` hook.
-There are three levels of styles to be applied: `useStyles` takes the HTML element type used in the component to normalize the styles according to those HTML elements.
-A base normalization is automatically added to this list and always applies in order to have the same defaults cross-browser.
-Next, `useStyles` takes a `variant` which is retrieved from the theme (which is given in the `<ThemeProvider>`). Additionally, you can insert custom styles
-which are applied on runtime and override normalization and theme styles. Lastly, you can use custom classnames and pass them to your component in the `useStyles` hook.
-
-```tsx
-const classNames = useStyles(
-  {
-    element: 'button',
-    variant: `button.${variant}`,
-  },
-  className
-);
-```
-
-### Put it together
-
-Don't forget imports, defaults and (optional) logic needed for your component as seen in the following example.
-
-```tsx
-import React from 'react';
-import { ThemeProvider, system } from '@marigold/system';
-import { render } from '@testing-library/react';
-
-const theme = {
-  ...anyTheme,
-  button: {
-    outlined: { // variant
-      border: '1px solid orange',
-      mx: 2,
-    },
-  },
-};
-// Define custom properties for your component
-type ButtonProps = {
-  kind?: 'basic' | 'other';
-  size?: 'small' | 'medium' | 'large';
-};
-
-// Specify the HTML element you want to render and merge its properties with the custom component props
-const Button = system<ButtonProps, 'button'>(
-  // Set default values for extra props
-  ({
-    kind = 'basic',
-    size = 'medium',
-    className
-    children,
-    ...props
-  }) => {
-    const classNames = useStyles(
-      // add normalization and variant
-      {
-        element: 'button',
-        variant: `button.${variant}`,
-      },
-      className
-    )
-    // Place logic here like toggle states, calculations, mappings etc.
-    return (
-      <button
-        className={classNames}
-        {...props}
-      >
-        <span
-          className={useStyles({ // use custom styles only
-            display: 'inline-flex',
-            alignItems: 'center',
-          })}
-        >
-          {children}
-        </span>
-      </button>
-    );
-  }
-);
-// Use the component; don't forget the imports
-render(
-  <ThemeProvider theme={theme}>
-    <Button /> // Default Button component instance
-  </ThemeProvider>
-);
-```
-
-### Folder Structure
-
-As we want to keep an organized file structure, we use a script to create new component templates. Navigate to the root folder and use it with `yarn create:component COMPONENTNAME`. The new component
-is generated with all files needed and already added to the component exports.
-
-```
-packages
-└─── system
-|
-└─── components
-      |    index.ts
-      |    theme.ts
-      └─── src
-            └─── Button
-                  |    index.ts
-                  |    Button.tsx
-                  |    Button.test.tsx
-                  |    Button.stories.mdx
-```