ACM: Admin-UI Component Model [WIP]

[matheusps]

ACM: Admin-UI Component Model

ACM presents a set of rules and best practices, that describes how Admin-UI components are created and used. It exists to standardize the API surface area of the design system functionalities, reducing the learning curve.

Table of contents

1. Component shapes.
2. Handling state.
3. Styling.

The learning curve theory [WIP]

The learning curve theory explains that as individuals or organizations accumulate experience, they initially experience rapid improvements in performance and cost reduction. However, as they reach higher levels of proficiency, the rate of improvement slows down until it eventually levels off. Understanding and leveraging the learning curve can help individuals and organizations optimize their processes, enhance productivity, and achieve long-term success.

Initially, when people begin a new task or venture, they experience a steep learning curve, indicating a slow rate of progress. This phase is characterized by trial and error, as individuals familiarize themselves with the task's intricacies and develop basic skills. As they gain experience, their performance improves gradually, and they become more efficient in completing the task. This early stage of learning is often associated with significant improvements in productivity and cost reduction.

Grasping the learning curve theory in reusable component API design helps create developer-friendly interfaces, anticipate and address potential challenges, and drive continuous improvement. By reducing the learning curve associated with the API, library creators can foster a positive developer experience and encourage wider adoption of their tooling.

The desing system evolves as people evolves. So, its a learning curve acuulmulator. Its. a shared knowledge enviroment : “/The industrial learning curve thus embraces more than the increasing skill of an individual by repetition of a simple operation. Instead, it describes a more complex organism—the collective efforts of many people, some in line and others in staff positions, but all aiming to accomplish a common task progressively more efficiently/“

How do Components surge [WIP]?

It's important to understand how components actually appear on a shared library, such as Admin UI.

Extraction

The component is data-locked and specialized.
The component gets abstracted and white-labeled.
The component is extracted into a reusable package.
All the instances specialize the abstraction.

Ideation

The component is created and then inserted.
Normally core components surge this way.

Promotion

A compound component exists.
An inner structure gets important.
This inner structure is extracted and then inserted.

// header/header.tsx

export interface HeaderProps {
  title: ReactNode,
  children?: ReactNode
  // ... other props
}

export function Header(props: HeaderProps) {
  const { title, /** ...rest */ } = props
  return (
    <header className="header">
      <h1 className="title">{title}</h1>
      {/** ... rest of the component */ }
    </header>
  )
}

// header/header.tsx

export interface HeaderProps {
  children?: ReactNode
  // ... other header props
}

export function Header(props: HeaderProps) {
  const { children, /** ...rest */ } = props
  return (
    <header className="header">
      {children}
      {/** ... rest of the component */ }
    </header>
  )
}

// header/title.tsx

export interface HeaderTitleProps {
  children?: ReactNode
  // ... other title props
}

export function HeaderTitle(props: HeaderTitleProps) {
  const { children } = props
  return (
    <h1 className="title">{children}</h1>
  )
}

The infinite abstraction hell

The solution: Don’t abstract what you don’t reuse in someplace.

The pace: Resolve a real-world example => Abtract => Ship => Do it all over again.

Book: Refactoring, Martin Fowler.
Methodology: AHA - Avoid Hasty Abstractions, Kent C. Dodds.

Component design

Whether you think of component API design, there are two main aspects that you must be concerned are Flexibility and Complexity.

1. Flexibility
2. Complexity

Every component design has its pros and cons. When you're choosing the pattern, try to be intentional, get to know your target audience, and be consistent with your ideas.

Remember that a good component design/API makes it easier for your audience to do the right thing, and harder for the wrong thing.

Stateless Components

<Potato size="large" />

import { useState } from 'react'

function Example() {
  const [isLarge, setIsLarge] = useState(true)
  
  const toggleSize = () => setSize((s) => )
  
  return (
    <Potato size={} />
  )
}

Composition

Parent relation: aka Children

Free property: aka Node properties

State hooks

When the state is too complex and you want a deeper level of control over it, you can abstract your state into a state hook that enables the state to be intercepted and changed before passing it to the stateless component. This model creates a good balance between consistency, simplicity, and flexibility.

const potato = usePotatoState()

<Potato state={potato} />

Another advantage is the reuse of behavior:

function useVegetable(vegableParams) {/** ... */}

function usePotato(params) {
  const { param1, ...vegetableParams } = params
  const vegetable = useVegetable(vetableParams)
  /** ... */
}

Component hooks

Use component hooks whether you need to

💡 They use the prop-getters pattern

const { potatoProps } = usePotato()

<div {...potatoProps} />

const { getPotatoProps } = usePotato()

// without additional behavior
<div {...getPotatoProps()} />

// with additional behavior 
<div {...getPotatoProps({
  onClick: () => console.log('potato in Portuguese is "batata"')
})} />

Stateful components

const [value, setValue] = React.useState()

<Potato value={value} onChange={(val) => setValue(val)} />

Typescript

Extend JSX elements

import type { ComponentProps } from 'react'

type DivProps = ComponentProps <'div'>

Styling

The styling model is designed to be agnostic for styling library

🚧 WIP 🚧

// potato.css.ts

import { csx } from '@vtex/sail-css'

export const potatoTheme = csx({
  color: 'purple'
})

// potato.tsx

import { potatoTheme } from './potato.css.ts'

export function Potato() {
  return (
    <div className={potatoTheme} />
  )
}

Variants

Variants are achieved with the help of class names and data-attributes.

Anti-patterns

Some anti-patterns that you must watch-out

The black box: aka Prop-drilling

Prop-drilling is not necessarily a problem.

function Header({ title, titleColor, tabs }) {
  return (
    <header className="header">
      <Title title={title} titleColor={titleColor}/> 
      <Tabs tabs={tabs} />
    </header>
  }
}

function Title({ title, titleColor }) {
	return (
    <h1 style={{ color: titleColor }}>{title}</h1>
  )
}

function Tabs({ tabs }) {
  return (
    <div className="tabs">
      {tabs.map(tab => (
        <Tab id={tab.id} key={tab.id} title={tab.title} />
      )}
    <div/>
  )
}

function Tab({ id, title }) {
  return (
    <button className="tab" id="id" type="button">
      {title}
    </button>
  )
}

This is how de component is used

<Header
  title="My page"
  titleColor="#000"
  tabs={[
    { id: 1, title: "Tab 1" },
    { id: 2, title: "Tab 2" },
  ]}
/>

Data always flows down…

function Header({ children }) {
  return (
    <header className="header">{children}</header>
  }
}

function Title({ color, children }) {
	return (
    <h1 className="title" style={{ color }}>{children}</h1>
  )
}

function Tabs({ children }) {
  return (
    <div className="tabs">{children}<div/>
  )
}

function Tab({ id, children }) {
  return (
    <button className="tab" id={id} type="button">
      {children}
    </button>
  )
}

<Header>
	<Title color="#000">My page</Title>
  <Tabs>
    <Tab id={1}>Tab 1</Tab>
    <Tab id={2}>Tab 2</Tab>
  </Tabs>
</Header>

Real case scenario:

Another page was created. It also has a header, but no tabs. In the current solution, you would add a if statement to make it work.

function Header({ title, titleColor, tabs }) {
  return (
    <header className="header">
      <Title title={title} titleColor={titleColor}/> 
		{!!tabs && <Tabs tabs={tabs} />}
    </header>
  }
}

This should do the trick.

TBD

The wizard HOC

TBD

References

• Profit from the learning curve, Havard business

[davicostalf]

@matheusps Is this discussion still relevant or is this content already in the documentation?