import { Meta, Source, Canvas } from '@storybook/addon-docs/blocks';
import * as stories from './SentimentSurface.story';

<Meta title="Foundations/SentimentSurface/Developer Guide" />

# Developer Guide

SentimentSurface is a polymorphic container component that exposes and, optionally, applies contextual colour tokens
as CSS custom properties, based on sentiment types (`negative`, `warning`, `neutral`, `success`, `proposition`).

## Available Tokens

Each `SentimentSurface` sets tokens for content, interactive elements, and background surfaces. See the [Tokens story](?path=/story/content-sentimentsurface--tokens) for a visual demonstration of all tokens across sentiments and emphasis levels:

<Source dark language="html" code={`
  --color-sentiment-content-primary
  --color-sentiment-content-primary-hover
  --color-sentiment-content-primary-active

--color-sentiment-interactive-primary
--color-sentiment-interactive-primary-hover
--color-sentiment-interactive-primary-active

--color-sentiment-interactive-secondary
--color-sentiment-interactive-secondary-hover
--color-sentiment-interactive-secondary-active

--color-sentiment-interactive-secondary-neutral
--color-sentiment-interactive-secondary-neutral-hover
--color-sentiment-interactive-secondary-neutral-active

--color-sentiment-interactive-control
--color-sentiment-interactive-control-hover
--color-sentiment-interactive-control-active

--color-sentiment-background-surface
--color-sentiment-background-surface-hover
--color-sentiment-background-surface-active
`} />

## Using Tokens in Components

When building `SentimentSurface`-aware components, the exposed tokens should be [referenced with fallbacks](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties#custom_property_fallback_values) to maintain functionality outside a said surfaces.

<Canvas of={stories.CustomComponents} />

## Polymorphic Rendering

The component is fully polymorphic, meaning it can render as any HTML element using the `as` prop while maintaining full type safety, accepting all valid HTML attributes for the rendered element:

<Source dark language="tsx" code={`
  // ✅ Renders as HTML 'section' with valid HTML attributes
  <SentimentSurface
    sentiment="negative"
    as="section"
    role="alert"
    aria-live="polite"
    data-position="top"
  >
    Critical error message
  </SentimentSurface>

// ❌ TypeScript error - 'href' is not a valid attribute for a 'div'

<SentimentSurface as="div" href="/link">
  Content
</SentimentSurface>
`} />

## Accessibility Considerations

The tokens provided by the component are designed with WCAG AA contrast ratios in mind:

- **Base emphasis**: Tokens provide sufficient contrast for body text
- **Elevated emphasis**: Tokens provide higher contrast, often with inverted colours

Always test your content for contrast compliance, especially when:

- Applying tokens via `style` or `className`
- Using small text sizes
- Displaying important information

### Further Reading

- [WCAG Color Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
- [ARIA Live Regions](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html)