npm package: @madajoe6969/style-core
Description: Unified style rendering system for MicroFeedback widgets
Author: MicroFeedback
Latest version: 1.0.0

# @my-better-t-app/style-core

Unified style rendering system for MicroFeedback widgets that ensures pixel-perfect consistency between dashboard customization and embedded widgets across HTML/JavaScript, React, and Vue implementations.

## Features

- **Unified Style Renderer**: Single source of truth for CSS generation across all widget implementations
- **Type-Safe Configuration**: Comprehensive TypeScript interfaces with Zod validation
- **Multiple Output Formats**: Generate CSS variables, CSS-in-JS objects, and styled-components themes
- **Responsive Design**: Built-in support for mobile and tablet breakpoints
- **Security**: CSS sanitization to prevent injection attacks
- **Framework Agnostic**: Works with vanilla HTML/JS, React, and Vue

## Installation

```bash
bun add @my-better-t-app/style-core
```

## Usage

### Basic Usage

```typescript
import { UnifiedStyleRenderer, createDefaultStyleConfig } from '@my-better-t-app/style-core';

// Create a renderer with default configuration
const config = createDefaultStyleConfig();
const renderer = new UnifiedStyleRenderer(config);

// Generate CSS variables
const variables = renderer.generateCSSVariables();

// Generate complete CSS stylesheet
const css = renderer.generateCSS('my-widget');

// Generate CSS-in-JS styles for React
const styles = renderer.generateCSSInJS();

// Generate styled-components theme
const theme = renderer.generateStyledComponentsTheme();
```

### Custom Configuration

```typescript
import { UnifiedStyleRenderer, validateStyleConfig } from '@my-better-t-app/style-core';

const customConfig = {
  version: "1.0.0",
  colors: {
    primary: "#ff6b35",
    background: "#ffffff",
    text: "#333333",
    border: "#e1e5e9",
  },
  typography: {
    fontFamily: "Inter, system-ui, sans-serif",
    fontSize: {
      small: "0.875rem",
      base: "1rem",
      large: "1.125rem",
    },
    fontWeight: {
      normal: 400,
      bold: 600,
    },
    lineHeight: 1.5,
  },
  // ... other configuration options
};

// Validate and sanitize the configuration
const validatedConfig = validateStyleConfig(customConfig);
const renderer = new UnifiedStyleRenderer(validatedConfig);
```

### Framework-Specific Usage

#### HTML/JavaScript

```typescript
// Generate scoped CSS for vanilla JS widgets
const css = renderer.generateCSS('microfeedback-widget-123');

// Inject styles into the page
const styleElement = document.createElement('style');
styleElement.textContent = css;
document.head.appendChild(styleElement);
```

#### React with styled-components

```typescript
import styled, { ThemeProvider } from 'styled-components';

const theme = renderer.generateStyledComponentsTheme();

const StyledWidget = styled.div`
  background-color: ${props => props.theme.colors.background};
  color: ${props => props.theme.colors.text};
  border-radius: ${props => props.theme.layout.borderRadius};
`;

function Widget() {
  return (
    <ThemeProvider theme={theme}>
      <StyledWidget>
        {/* Widget content */}
      </StyledWidget>
    </ThemeProvider>
  );
}
```

#### Vue with CSS Variables

```vue
<template>
  <div class="widget" :style="cssVariables">
    <!-- Widget content -->
  </div>
</template>

<script>
export default {
  computed: {
    cssVariables() {
      return this.renderer.generateCSSVariables();
    }
  }
}
</script>

<style scoped>
.widget {
  background-color: var(--mf-background-color);
  color: var(--mf-text-color);
  border-radius: var(--mf-border-radius);
}
</style>
```

## API Reference

### UnifiedStyleRenderer

The main class for generating consistent styles across all widget implementations.

#### Methods

- `generateCSSVariables()`: Returns CSS custom properties object
- `generateCSS(scope?)`: Returns complete CSS stylesheet with optional scoping
- `generateCSSInJS()`: Returns CSS-in-JS style objects for React
- `generateStyledComponentsTheme()`: Returns theme object for styled-components
- `getConfig()`: Returns current configuration
- `updateConfig(newConfig)`: Returns new renderer instance with updated configuration

### Validation Functions

- `validateStyleConfig(config)`: Validates configuration against schema
- `createDefaultStyleConfig()`: Creates a valid default configuration
- `sanitizeStyleConfig(config)`: Validates and sanitizes configuration
- `sanitizeCSSValue(value)`: Sanitizes individual CSS values

## Configuration Schema

See the TypeScript interfaces in the source code for the complete configuration schema. The main interface is `WidgetStyleConfig` which includes:

- `colors`: Primary, background, text, border, error, success colors
- `typography`: Font family, sizes, weights, line height
- `layout`: Border radius, padding, margins, spacing
- `interactions`: Hover effects, focus styles, transitions
- `responsive`: Mobile and tablet-specific overrides
- `accessibility`: High contrast, reduced motion options

## Development

```bash
# Install dependencies
bun install

# Build the package
bun run build

# Run tests
bun run test

# Type checking
bun run check-types
```