@pushwoosh/kit-typography 1.7.3 → 1.7.5

package/ai-documentation.md

@@ -0,0 +1,243 @@
+# @pushwoosh/kit-typography - AI Agent Documentation
+
+## Overview
+React typography component library for Pushwoosh products. Provides styled-components based typography components with consistent design system.
+
+## Installation
+```bash
+npm install @pushwoosh/kit-typography
+```
+
+## Core Dependencies
+- **react**: >= 16.14.0 (peer dependency)
+- **styled-components**: >= 5.3.3 (peer dependency)
+- **@pushwoosh/kit-constants**: Typography constants (fonts, sizes, weights, line-heights, colors)
+
+## Available Components
+
+### Heading Components
+- **H1**: Main page heading (`<h1>`)
+- **H2**: Section heading (`<h2>`)
+- **H3**: Subsection heading (`<h3>`)
+- **H4**: Small heading (`<h4>`)
+- **H5**: Smallest heading (`<h5>`)
+
+All heading components accept:
+- `boxRef`: React ref for the HTML element
+- `children`: React.ReactNode
+- All standard HTML heading attributes
+
+### Text Components
+
+#### Paragraph
+Standard paragraph component (`<p>`)
+```tsx
+import { Paragraph } from '@pushwoosh/kit-typography';
+<Paragraph>Your text content</Paragraph>
+```
+
+#### Footnote
+Small text for footnotes/captions
+```tsx
+import { Footnote } from '@pushwoosh/kit-typography';
+<Footnote>Small text content</Footnote>
+```
+
+#### Code
+Monospace text for code snippets (`<code>`)
+```tsx
+import { Code } from '@pushwoosh/kit-typography';
+<Code>console.log('Hello')</Code>
+```
+
+### Universal Text Component
+
+#### Text
+Flexible styled span component with variant support
+```tsx
+import { Text } from '@pushwoosh/kit-typography';
+
+// Basic usage
+<Text>Default text</Text>
+
+// With variant
+<Text $variant="h1">Large heading text</Text>
+<Text $variant="footnote">Small text</Text>
+<Text $variant="code">Monospace text</Text>
+
+// With props
+<Text $color="#FF0000">Red text</Text>
+<Text $uppercase>UPPERCASE TEXT</Text>
+<Text $ellipsis>Long text with ellipsis...</Text>
+
+// Combined
+<Text $variant="h2" $color="#0066CC" $uppercase>BLUE HEADING</Text>
+```
+
+**Props:**
+- `$variant`: TypographyVariant - style preset ('standard' | 'footnote' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'code')
+- `$color`: string - custom text color
+- `$uppercase`: boolean - transform text to uppercase
+- `$ellipsis`: boolean - add text overflow ellipsis
+
+### Global Styles
+
+Apply consistent typography and base styles across the application:
+```tsx
+import { GlobalStyles } from '@pushwoosh/kit-typography';
+
+// In your app root
+function App() {
+  return (
+    <>
+      <GlobalStyles />
+      {/* Your app components */}
+    </>
+  );
+}
+```
+
+Sets:
+- Box-sizing: border-box for all elements
+- Body typography: main font, regular size/weight
+- Link styles: primary color with hover effects
+- Focus outline removal on buttons/links
+- Font smoothing for better rendering
+
+## Typography Variants
+
+Available through `TypographyVariant` type and used in Text component:
+
+| Variant | Font Family | Size | Weight | Line Height |
+|---------|------------|------|--------|-------------|
+| standard | MAIN | REGULAR | REGULAR | REGULAR |
+| footnote | MAIN | SMALL | REGULAR | SMALL |
+| h1 | MAIN | HEADING1 | BOLD | HEADING1 |
+| h2 | MAIN | HEADING2 | BOLD | HEADING2 |
+| h3 | MAIN | HEADING3 | BOLD | HEADING3 |
+| h4 | MAIN | HEADING4 | MEDIUM | HEADING4 |
+| h5 | MAIN | HEADING5 | MEDIUM | HEADING5 |
+| code | MONO | REGULAR | REGULAR | REGULAR |
+
+## Usage Examples
+
+### Complete page structure
+```tsx
+import { 
+  GlobalStyles, 
+  H1, 
+  H2, 
+  Paragraph, 
+  Text, 
+  Code,
+  Footnote 
+} from '@pushwoosh/kit-typography';
+
+function Page() {
+  return (
+    <>
+      <GlobalStyles />
+      <H1>Page Title</H1>
+      <Paragraph>
+        Introduction paragraph with <Text $color="#0066CC">highlighted</Text> text.
+      </Paragraph>
+      
+      <H2>Section Title</H2>
+      <Paragraph>
+        Section content with <Code>inline code</Code> example.
+      </Paragraph>
+      
+      <Text $variant="h3" $uppercase>SUBSECTION</Text>
+      <Footnote>Note: Additional information</Footnote>
+    </>
+  );
+}
+```
+
+### Dynamic text styling
+```tsx
+import { Text } from '@pushwoosh/kit-typography';
+
+function StatusText({ status, message }) {
+  const color = status === 'error' ? '#FF0000' : '#00AA00';
+  return (
+    <Text 
+      $color={color}
+      $variant={status === 'error' ? 'h4' : 'standard'}
+      $uppercase={status === 'error'}
+    >
+      {message}
+    </Text>
+  );
+}
+```
+
+### Text truncation
+```tsx
+import { Text } from '@pushwoosh/kit-typography';
+
+function UserCard({ userName, userEmail }) {
+  return (
+    <div style={{ width: '200px' }}>
+      <Text $variant="h5">{userName}</Text>
+      <Text $ellipsis $color="#666">{userEmail}</Text>
+    </div>
+  );
+}
+```
+
+## Development Scripts
+
+- `npm start` / `npm run playground`: Start development playground
+- `npm run build`: Build the library
+- `npm run check`: Run linting and type checking
+- `npm run check:lint`: Run ESLint
+- `npm run check:types`: Check TypeScript types
+
+## File Structure
+
+```
+src/
+├── index.tsx           # Main exports
+├── map.ts             # Typography variants configuration
+├── text/
+│   └── Text.ts        # Universal Text component
+├── global-styles/     # Global CSS styles
+├── h1-h5/            # Heading components
+├── paragraph/        # Paragraph component
+├── footnote/         # Footnote component
+└── code/             # Code component
+```
+
+Each component folder contains:
+- `index.tsx`: Component export
+- `[name].component.tsx`: React component
+- `[name].styles.tsx`: Styled-components styles
+- `[name].types.tsx`: TypeScript types
+
+## Best Practices
+
+1. **Always include GlobalStyles** in your app root for consistent base styling
+2. **Use semantic components** (H1, Paragraph) for better HTML structure
+3. **Use Text component** for inline styling needs and dynamic variants
+4. **Leverage $ellipsis** for text truncation in constrained layouts
+5. **Import from package root**: `import { H1, Text } from '@pushwoosh/kit-typography'`
+6. **Maintain hierarchy**: Use heading levels (H1→H2→H3) in proper order
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+- Component props types for all components
+- `TypographyVariant` type for Text component variants
+- Proper HTML element attribute inheritance
+
+## Integration with Pushwoosh Design System
+
+This library uses `@pushwoosh/kit-constants` for all design tokens:
+- **FontFamily**: MAIN, MONO
+- **FontSize**: SMALL, REGULAR, HEADING1-5
+- **FontWeight**: REGULAR, MEDIUM, BOLD
+- **LineHeight**: SMALL, REGULAR, HEADING1-5
+- **Color**: MAIN, PRIMARY, PRIMARY_HOVER
+
+Ensures consistency across all Pushwoosh products.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/kit-typography",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "description": "React component for build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",
@@ -8,7 +8,7 @@
   "sideEffects": false,
   "scripts": {
     "start": "npm run playground",
-    "build": "pushwoosh-engine lib:build",
+    "build": "pushwoosh-engine lib:build && cp ai-documentation.md dist/ai-documentation.md",
     "playground": "pushwoosh-engine lib:playground",
     "check": "npm run check:lint && npm run check:types",
     "check:lint": "echo \"Run check:lint\" && eslint .",