desktop-team-doc 0.1.0

package/content/tools/skills/frontend-develop/references/component-reusability.md

@@ -0,0 +1,559 @@
+# Component Reusability Guidelines
+
+This document provides comprehensive guidelines for creating reusable components, including using existing components, variant design patterns, and extensibility considerations.
+
+## Core Principles
+
+### Prioritize Existing Components
+
+**Rule**: Always check for existing components before creating new ones.
+
+**Process**:
+1. Search codebase for similar components
+2. Check component library (`@positivegrid/pg-react-ui-library`)
+3. Review common components (`components/common/`)
+4. If similar component exists, extend or compose it
+5. Only create new component if no suitable option exists
+
+### Component Discovery
+
+**Where to Look**:
+- `src/components/common/` - Shared utility components
+- `next/components/common/` - Newer common components
+- `src/components/dumbs/` - Presentational components
+- `@positivegrid/pg-react-ui-library` - Internal component library
+
+**Example**:
+```typescript
+// Before creating new button
+import { AppButton } from '@/src/components/common';
+// or
+import { Button } from '@positivegrid/pg-react-ui-library';
+
+// Use existing component
+<AppButton onClick={handleClick} disabled={isDisabled}>
+  Click Me
+</AppButton>
+```
+
+## Variant Design Patterns
+
+### When to Use Variants
+
+Use variants when:
+1. Component has multiple visual styles
+2. Component has different behaviors based on props
+3. Component needs to support different sizes, colors, or states
+4. Component variations are related and share core functionality
+
+### Variant Design Best Practices
+
+#### Pattern 1: Union Type Variants
+
+**Rule**: Use union types for simple, mutually exclusive variants.
+
+**Example**:
+```typescript
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'danger';
+  size?: 'small' | 'medium' | 'large';
+  disabled?: boolean;
+}
+
+function Button({
+  variant = 'primary',
+  size = 'medium',
+  disabled = false,
+  ...props
+}: ButtonProps): JSX.Element {
+  return (
+    <button
+      className={clsx(
+        'btn',
+        `btn-${variant}`,
+        `btn-${size}`,
+        { 'btn-disabled': disabled }
+      )}
+      disabled={disabled}
+      {...props}
+    />
+  );
+}
+```
+
+#### Pattern 2: Discriminated Union for Complex Variants
+
+**Rule**: Use discriminated unions when variants have different prop requirements.
+
+**Example**:
+```typescript
+type BaseButtonProps = {
+  onClick: () => void;
+  disabled?: boolean;
+};
+
+type IconButtonProps = BaseButtonProps & {
+  variant: 'icon';
+  icon: React.ReactNode;
+  'aria-label': string;
+};
+
+type TextButtonProps = BaseButtonProps & {
+  variant: 'text';
+  label: string;
+};
+
+type ButtonProps = IconButtonProps | TextButtonProps;
+
+function Button(props: ButtonProps): JSX.Element {
+  if (props.variant === 'icon') {
+    return (
+      <button onClick={props.onClick} aria-label={props['aria-label']}>
+        {props.icon}
+      </button>
+    );
+  }
+  
+  return (
+    <button onClick={props.onClick}>
+      {props.label}
+    </button>
+  );
+}
+```
+
+#### Pattern 3: Variant Combinations
+
+**Rule**: Consider variant combinations and ensure they work together.
+
+**Example**:
+```typescript
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'outline';
+  size?: 'small' | 'medium' | 'large';
+  loading?: boolean;
+  disabled?: boolean;
+  fullWidth?: boolean;
+}
+
+function Button({
+  variant = 'primary',
+  size = 'medium',
+  loading = false,
+  disabled = false,
+  fullWidth = false,
+  children,
+  ...props
+}: ButtonProps): JSX.Element {
+  // Ensure variants work together
+  const isDisabled = disabled || loading;
+  
+  return (
+    <button
+      className={clsx(
+        'btn',
+        `btn-${variant}`,
+        `btn-${size}`,
+        {
+          'btn-loading': loading,
+          'btn-disabled': isDisabled,
+          'btn-full-width': fullWidth,
+        }
+      )}
+      disabled={isDisabled}
+      {...props}
+    >
+      {loading ? <Spinner /> : children}
+    </button>
+  );
+}
+```
+
+### Variant Count Considerations
+
+**Rule**: Limit variant combinations to prevent complexity explosion.
+
+**Guidelines**:
+- **2-3 variants per dimension**: Keep variant dimensions manageable
+- **Total combinations < 20**: Avoid too many combinations
+- **Document combinations**: Document which combinations are supported
+
+**Example**:
+```typescript
+// Good: 3 variants × 3 sizes = 9 combinations (manageable)
+type Variant = 'primary' | 'secondary' | 'outline';
+type Size = 'small' | 'medium' | 'large';
+
+// Bad: 5 variants × 5 sizes × 4 states = 100 combinations (too many)
+type Variant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'link';
+type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type State = 'default' | 'hover' | 'active' | 'disabled';
+```
+
+### Variant Composition
+
+**Rule**: Compose variants from smaller, reusable pieces.
+
+**Example**:
+```typescript
+// Base button styles
+const baseButtonStyles = 'px-4 py-2 rounded font-medium transition';
+
+// Variant-specific styles
+const variantStyles = {
+  primary: 'bg-blue-500 text-white hover:bg-blue-600',
+  secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
+  outline: 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50',
+};
+
+// Size-specific styles
+const sizeStyles = {
+  small: 'px-2 py-1 text-sm',
+  medium: 'px-4 py-2 text-base',
+  large: 'px-6 py-3 text-lg',
+};
+
+function Button({
+  variant = 'primary',
+  size = 'medium',
+  ...props
+}: ButtonProps): JSX.Element {
+  return (
+    <button
+      className={twMerge(
+        baseButtonStyles,
+        variantStyles[variant],
+        sizeStyles[size]
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## Component Extensibility
+
+### Props Extension Pattern
+
+**Rule**: Allow component extension through props spreading (when intentional).
+
+**Example**:
+```typescript
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary';
+  loading?: boolean;
+}
+
+function Button({
+  variant = 'primary',
+  loading = false,
+  className,
+  children,
+  ...buttonProps
+}: ButtonProps): JSX.Element {
+  return (
+    <button
+      className={twMerge('btn', `btn-${variant}`, className)}
+      disabled={loading || buttonProps.disabled}
+      {...buttonProps}
+    >
+      {loading ? <Spinner /> : children}
+    </button>
+  );
+}
+```
+
+### Composition Pattern
+
+**Rule**: Prefer composition over complex variant systems.
+
+**Example**:
+```typescript
+// Instead of one complex component with many variants
+function ComplexButton({ variant, icon, label, badge, ... }) {
+  // Complex logic handling all combinations
+}
+
+// Use composition
+interface ButtonGroupProps {
+  children: React.ReactNode;
+}
+
+interface ButtonIconProps {
+  icon: React.ReactNode;
+}
+
+interface ButtonBadgeProps {
+  count: number;
+}
+
+function ButtonGroup({ children }: ButtonGroupProps) {
+  return <div className="btn-group">{children}</div>;
+}
+
+function Button({ children, ...props }: ButtonProps) {
+  return <button {...props}>{children}</button>;
+}
+
+function ButtonIcon({ icon }: ButtonIconProps) {
+  return <span className="btn-icon">{icon}</span>;
+}
+
+function ButtonBadge({ count }: ButtonBadgeProps) {
+  return <span className="btn-badge">{count}</span>;
+}
+
+// Usage: Compose as needed
+<ButtonGroup>
+  <Button>
+    <ButtonIcon icon={<Icon />} />
+    Label
+    <ButtonBadge count={5} />
+  </Button>
+</ButtonGroup>
+```
+
+### Render Props Pattern
+
+**Rule**: Use render props for maximum flexibility.
+
+**Example**:
+```typescript
+interface AutomationWrapperProps {
+  parameterId: string;
+  children: (props: {
+    isHighlighted: boolean;
+    onClick: () => void;
+    onContextMenu: (e: React.MouseEvent) => void;
+  }) => React.ReactNode;
+}
+
+function AutomationWrapper({
+  parameterId,
+  children,
+}: AutomationWrapperProps): JSX.Element {
+  const { isHighlighted, handleClick, handleContextMenu } = useAutomation(parameterId);
+
+  return (
+    <>
+      {children({
+        isHighlighted,
+        onClick: handleClick,
+        onContextMenu: handleContextMenu,
+      })}
+    </>
+  );
+}
+
+// Usage
+<AutomationWrapper parameterId="gain">
+  {({ isHighlighted, onClick, onContextMenu }) => (
+    <Knob
+      value={value}
+      onChange={onChange}
+      onClick={onClick}
+      onContextMenu={onContextMenu}
+      className={clsx({ 'highlighted': isHighlighted })}
+    />
+  )}
+</AutomationWrapper>
+```
+
+## Following Existing Component Design Rules
+
+### Study Existing Patterns
+
+**Rule**: Study existing components to understand design patterns.
+
+**Checklist**:
+- [ ] Review similar components in codebase
+- [ ] Understand prop naming conventions
+- [ ] Follow styling patterns (TailwindCSS classes)
+- [ ] Match component structure (imports, types, hooks, handlers, render)
+- [ ] Use same utility functions (`twMerge`, `clsx`)
+
+### Example: Following Button Pattern
+
+**Existing Pattern**:
+```typescript
+// Existing AppButton component
+export interface AppButtonProps {
+  disable?: boolean;
+  selected?: boolean;
+  className?: string;
+  onClick?: () => void;
+}
+
+function AppButton({
+  disable = false,
+  selected = false,
+  className,
+  onClick,
+  children,
+}: AppButtonProps): JSX.Element {
+  return (
+    <button
+      className={twMerge(
+        'x-btn',
+        {
+          'x-btn-disabled': disable,
+          'x-btn-selected': selected,
+        },
+        className
+      )}
+      disabled={disable}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+**New Component Following Pattern**:
+```typescript
+// New IconButton following same pattern
+export interface IconButtonProps {
+  disable?: boolean;
+  selected?: boolean;
+  className?: string;
+  onClick?: () => void;
+  icon: React.ReactNode;
+}
+
+function IconButton({
+  disable = false,
+  selected = false,
+  className,
+  onClick,
+  icon,
+}: IconButtonProps): JSX.Element {
+  return (
+    <button
+      className={twMerge(
+        'x-btn-icon',
+        {
+          'x-btn-icon-disabled': disable,
+          'x-btn-icon-selected': selected,
+        },
+        className
+      )}
+      disabled={disable}
+      onClick={onClick}
+    >
+      {icon}
+    </button>
+  );
+}
+```
+
+## Component Library Integration
+
+### Using Internal Component Library
+
+**Rule**: Prefer components from `@positivegrid/pg-react-ui-library` when available.
+
+**Example**:
+```typescript
+import { Button, Input, Select } from '@positivegrid/pg-react-ui-library';
+
+function Form() {
+  return (
+    <form>
+      <Input placeholder="Name" />
+      <Select options={options} />
+      <Button onClick={handleSubmit}>Submit</Button>
+    </form>
+  );
+}
+```
+
+### Extending Library Components
+
+**Rule**: Extend library components when customization is needed.
+
+**Example**:
+```typescript
+import { Button as BaseButton } from '@positivegrid/pg-react-ui-library';
+import { twMerge } from 'tailwind-merge';
+
+interface CustomButtonProps extends React.ComponentProps<typeof BaseButton> {
+  customVariant?: 'special';
+}
+
+function CustomButton({
+  customVariant,
+  className,
+  ...props
+}: CustomButtonProps): JSX.Element {
+  return (
+    <BaseButton
+      className={twMerge(
+        customVariant === 'special' && 'custom-special-style',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## Avoiding Duplicate Development
+
+### Component Search Checklist
+
+Before creating a new component:
+
+- [ ] Search codebase for similar functionality
+- [ ] Check `components/common/` directory
+- [ ] Review `components/dumbs/` for presentational components
+- [ ] Check `@positivegrid/pg-react-ui-library`
+- [ ] Review recent PRs for similar components
+- [ ] Ask team if component exists elsewhere
+
+### Refactoring Existing Components
+
+**Rule**: Refactor existing components instead of creating duplicates.
+
+**Example**:
+```typescript
+// Instead of creating new component
+function NewButton() {
+  // Similar to existing AppButton
+}
+
+// Refactor existing component
+export interface AppButtonProps {
+  variant?: 'primary' | 'secondary'; // Add variant support
+  size?: 'small' | 'medium' | 'large'; // Add size support
+  // ... existing props
+}
+
+function AppButton({
+  variant = 'primary',
+  size = 'medium',
+  ...existingProps
+}: AppButtonProps): JSX.Element {
+  // Extend existing implementation
+}
+```
+
+## Summary Checklist
+
+When creating or using components, ensure:
+
+- [ ] Existing components checked before creating new ones
+- [ ] Variants designed with manageable combinations (< 20 total)
+- [ ] Variant dimensions limited (2-3 per dimension)
+- [ ] Component follows existing design patterns
+- [ ] Props allow extension when needed
+- [ ] Composition preferred over complex variants
+- [ ] Component library components used when available
+- [ ] No duplicate components created
+- [ ] Existing components refactored instead of duplicated
+
+## References
+
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`
+- [Code Organization Guidelines](./code-organization.md)
+- [Type Safety Guidelines](./type-safety.md)