xrpl-dev-portal/shared/components/SmallTilesSection/SmallTilesSection.md

# SmallTilesSection Component

A section component that displays multiple CardIcon components in a responsive grid layout. This component is tightly coupled to CardIcon and creates a grouping of card icons with consistent styling and behavior.

## Overview

The SmallTilesSection component provides:

- Responsive grid layout (1 column mobile, 2 tablet, 3 desktop)
- Automatic spacer optimization for small card sets (≤8 cards)
- Consistent variant application across all cards
- Semantic HTML structure with proper accessibility

## Basic Usage

```tsx
import { SmallTilesSection } from "@/shared/components/SmallTilesSection/SmallTilesSection";

function MyComponent() {
  const cards = [
    {
      icon: "/icons/javascript.svg",
      iconAlt: "JavaScript",
      label: "JavaScript",
      href: "/docs/javascript",
    },
    {
      icon: "/icons/python.svg",
      iconAlt: "Python",
      label: "Python",
      href: "/docs/python",
    },
  ];

  return (
    <SmallTilesSection
      headline="Language Tutorials"
      subtitle="Choose a language to get started"
      cardVariant="neutral"
      cards={cards}
    />
  );
}
```

## Props

| Prop          | Type                            | Required | Description                                         |
| ------------- | ------------------------------- | -------- | --------------------------------------------------- |
| `headline`    | `React.ReactNode`               | Yes      | Section headline displayed as h2                    |
| `subtitle`    | `React.ReactNode`               | No       | Optional subtitle text displayed below headline     |
| `cardVariant` | `'neutral' \| 'green'`          | Yes      | Color variant applied to all cards in the section   |
| `cards`       | `CardIconProps[]`               | Yes      | Array of card configurations (without variant prop) |
| `className`   | `string`                        | No       | Additional CSS classes for the section element      |
| `...rest`     | `HTMLSectionElement attributes` | No       | Any other HTML section element attributes           |

## Card Props

Each item in the `cards` array accepts all CardIcon props except `variant` (which is controlled by `cardVariant`):

| Prop        | Type         | Required | Description                           |
| ----------- | ------------ | -------- | ------------------------------------- |
| `icon`      | `string`     | Yes      | Icon image source (URL or path)       |
| `iconAlt`   | `string`     | No       | Alt text for the icon image           |
| `label`     | `string`     | Yes      | Card label text                       |
| `href`      | `string`     | No       | Link destination (renders as `<a>`)   |
| `onClick`   | `() => void` | No       | Click handler (renders as `<button>`) |
| `disabled`  | `boolean`    | No       | Disabled state                        |
| `className` | `string`     | No       | Additional CSS classes                |

## Examples

### Basic Usage with Links

```tsx
<SmallTilesSection
  headline="Development Tools"
  subtitle="Explore our available tools"
  cardVariant="neutral"
  cards={[
    { icon: "/icons/js.svg", label: "xrpl.js", href: "/docs/xrpl-js" },
    { icon: "/icons/py.svg", label: "xrpl-py", href: "/docs/xrpl-py" },
    { icon: "/icons/go.svg", label: "xrpl-go", href: "/docs/xrpl-go" },
  ]}
/>
```

### Without Subtitle

```tsx
<SmallTilesSection headline="Quick Links" cardVariant="neutral" cards={cards} />
```

### Green Variant

```tsx
<SmallTilesSection
  headline="Featured Topics"
  subtitle="Recommended content to help you get started"
  cardVariant="green"
  cards={featuredCards}
/>
```

### Mixed Card States

Cards can have different interaction types within the same section:

```tsx
<SmallTilesSection
  headline="Mixed States Example"
  cardVariant="neutral"
  cards={[
    { icon: "/icon.svg", label: "Link Card", href: "/link" },
    { icon: "/icon.svg", label: "Button Card", onClick: () => handleClick() },
    { icon: "/icon.svg", label: "Disabled Card", disabled: true },
  ]}
/>
```

### Large Card Set (Spacer Feature)

When a section contains more than 8 cards, the component automatically adjusts the layout:

```tsx
<SmallTilesSection
  headline="All Topics"
  subtitle={`${largeCardSet.length} topics available`}
  cardVariant="neutral"
  cards={largeCardSet} // 9+ cards
/>
```

## Responsive Behavior

The grid automatically adjusts based on viewport width:

| Breakpoint             | Columns | Layout              |
| ---------------------- | ------- | ------------------- |
| Mobile (< 576px)       | 1       | Single column stack |
| Tablet (576px - 991px) | 2       | Two column grid     |
| Desktop (≥ 992px)      | 3       | Three column grid   |

### Spacer Feature

When card count is ≤8, the component uses a centered 2-column layout on large screens with automatic spacing. This ensures optimal visual alignment for smaller card sets.

## TypeScript Types

```typescript
interface SmallTilesSectionProps
  extends React.ComponentPropsWithoutRef<"section"> {
  headline: React.ReactNode;
  subtitle?: React.ReactNode;
  cardVariant: "neutral" | "green";
  cards: readonly Omit<CardIconProps, "variant">[];
}

// CardIconProps (without variant)
interface ConstrainedCardIconProps {
  icon: string;
  iconAlt?: string;
  label: string;
  href?: string;
  onClick?: () => void;
  disabled?: boolean;
  className?: string;
}
```

## Best Practices

1. **Consistent Variants**: Use the same `cardVariant` for all cards in a section to maintain visual consistency
2. **Stable Keys**: Cards with `href` or `label` properties will generate stable keys automatically
3. **Empty Arrays**: Component returns `null` if cards array is empty - no need to conditionally render
4. **Accessibility**: Ensure `iconAlt` is provided for meaningful icons to improve screen reader support
5. **Semantic Structure**: The component uses semantic HTML (`<section>`, `<h2>`, `<ul>`) for proper document structure

## Notes

- The component is tightly coupled to `CardIcon` - all cards must use CardIcon props
- All cards in a section share the same `variant` for visual consistency
- The spacer feature (≤8 cards) only affects large screen layouts
- Component forwards refs, allowing you to attach refs to the section element
- Cards are memoized individually to optimize re-render performance