@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/Text.md

@@ -0,0 +1,463 @@
+# Text
+
+A comprehensive text component that provides a standardized way to display text content with consistent typography. It offers extensive customization options including different text types, weights, decorations, transformations, and layout controls, making it the foundation for all text display in the UI.
+
+## Aliases
+
+- Text
+- Typography
+- TextElement
+
+## Props Breakdown
+
+**Extends:** Standalone interface (no HTML element inheritance)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `className` | `string` | `undefined` | No | Additional class for styling |
+| `type` | `'Heading1' \| 'Heading2' \| 'Heading3' \| 'Heading4' \| 'Heading5' \| 'Heading6' \| 'BodyLarge' \| 'BodyMedium' \| 'BodySmall'` | `'BodyMedium'` | No | Type of the text |
+| `weight` | `'Thin' \| 'ExtraLight' \| 'Light' \| 'Regular' \| 'Medium' \| 'SemiBold' \| 'Bold' \| 'ExtraBold' \| 'Black' \| 'ExtraBlack' \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 950` | `'Regular'` | No | Weight of the text |
+| `children` | `ReactNode` | `undefined` | No | The content to be displayed as text |
+| `noWrap` | `boolean` | `false` | No | Flag to prevent text from wrapping |
+| `whiteSpaceNoWrap` | `boolean` | `false` | No | Flag to handle how white space inside an element is handled |
+| `italic` | `boolean` | `false` | No | Flag to italicize the text |
+| `decoration` | `'None' \| 'Underline' \| 'Strikethrough'` | `'None'` | No | Decoration style for the text |
+| `ellipsis` | `boolean` | `false` | No | Flag to show ellipsis for overflowing text |
+| `transform` | `'None' \| 'Capitalize' \| 'UpperCase' \| 'LowerCase'` | `'None'` | No | Transform style for the text |
+| `as` | `React.ElementType` | `undefined` | No | Modify the element type used for rendering |
+
+This component uses a polymorphic `as` prop to render different HTML elements while maintaining consistent styling.
+
+## Examples
+
+### Basic Text Types
+
+```tsx
+import { Text } from '@delightui/components';
+
+function BasicTextTypesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Text type="Heading1">Heading 1 Text</Text>
+      <Text type="Heading2">Heading 2 Text</Text>
+      <Text type="Heading3">Heading 3 Text</Text>
+      <Text type="Heading4">Heading 4 Text</Text>
+      <Text type="Heading5">Heading 5 Text</Text>
+      <Text type="Heading6">Heading 6 Text</Text>
+      <Text type="BodyLarge">Body Large Text</Text>
+      <Text type="BodyMedium">Body Medium Text (Default)</Text>
+      <Text type="BodySmall">Body Small Text</Text>
+    </div>
+  );
+}
+```
+
+### Text Weights
+
+```tsx
+import { Text } from '@delightui/components';
+
+function TextWeightsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      <Text weight="Thin">Thin Weight (100)</Text>
+      <Text weight="ExtraLight">Extra Light Weight (200)</Text>
+      <Text weight="Light">Light Weight (300)</Text>
+      <Text weight="Regular">Regular Weight (400)</Text>
+      <Text weight="Medium">Medium Weight (500)</Text>
+      <Text weight="SemiBold">Semi Bold Weight (600)</Text>
+      <Text weight="Bold">Bold Weight (700)</Text>
+      <Text weight="ExtraBold">Extra Bold Weight (800)</Text>
+      <Text weight="Black">Black Weight (900)</Text>
+      <Text weight="ExtraBlack">Extra Black Weight (950)</Text>
+    </div>
+  );
+}
+```
+
+### Numeric Font Weights
+
+```tsx
+import { Text } from '@delightui/components';
+
+function NumericWeightsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      <Text weight={100}>Weight 100</Text>
+      <Text weight={200}>Weight 200</Text>
+      <Text weight={300}>Weight 300</Text>
+      <Text weight={400}>Weight 400</Text>
+      <Text weight={500}>Weight 500</Text>
+      <Text weight={600}>Weight 600</Text>
+      <Text weight={700}>Weight 700</Text>
+      <Text weight={800}>Weight 800</Text>
+      <Text weight={900}>Weight 900</Text>
+    </div>
+  );
+}
+```
+
+### Text Decorations
+
+```tsx
+import { Text } from '@delightui/components';
+
+function TextDecorationsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <Text decoration="None">Normal text without decoration</Text>
+      <Text decoration="Underline">Underlined text</Text>
+      <Text decoration="Strikethrough">Strikethrough text</Text>
+      
+      <Text decoration="Underline" weight="Bold">
+        Bold underlined text
+      </Text>
+      
+      <Text decoration="Strikethrough" italic>
+        Italic strikethrough text
+      </Text>
+    </div>
+  );
+}
+```
+
+### Text Transformations
+
+```tsx
+import { Text } from '@delightui/components';
+
+function TextTransformationsExample() {
+  const sampleText = "this is sample text for transformation";
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <Text transform="None">{sampleText}</Text>
+      <Text transform="Capitalize">{sampleText}</Text>
+      <Text transform="UpperCase">{sampleText}</Text>
+      <Text transform="LowerCase">{sampleText.toUpperCase()}</Text>
+    </div>
+  );
+}
+```
+
+### Italic Text
+
+```tsx
+import { Text } from '@delightui/components';
+
+function ItalicTextExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <Text>Normal text</Text>
+      <Text italic>Italic text</Text>
+      <Text italic weight="Bold">Bold italic text</Text>
+      <Text italic type="Heading3">Italic heading</Text>
+    </div>
+  );
+}
+```
+
+### Text Wrapping and Ellipsis
+
+```tsx
+import { Text } from '@delightui/components';
+
+function TextWrappingExample() {
+  const longText = "This is a very long text that will demonstrate how the text wrapping and ellipsis properties work with different configurations.";
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <div style={{ width: '250px', border: '1px solid #ccc', padding: '12px' }}>
+        <Text weight="Bold" style={{ marginBottom: '8px' }}>Normal Wrapping:</Text>
+        <Text>{longText}</Text>
+      </div>
+
+      <div style={{ width: '250px', border: '1px solid #ccc', padding: '12px' }}>
+        <Text weight="Bold" style={{ marginBottom: '8px' }}>No Wrap:</Text>
+        <Text noWrap>{longText}</Text>
+      </div>
+
+      <div style={{ width: '250px', border: '1px solid #ccc', padding: '12px' }}>
+        <Text weight="Bold" style={{ marginBottom: '8px' }}>With Ellipsis:</Text>
+        <Text ellipsis>{longText}</Text>
+      </div>
+
+      <div style={{ width: '250px', border: '1px solid #ccc', padding: '12px' }}>
+        <Text weight="Bold" style={{ marginBottom: '8px' }}>White Space No Wrap:</Text>
+        <Text whiteSpaceNoWrap>{"Text with    multiple    spaces    preserved"}</Text>
+      </div>
+    </div>
+  );
+}
+```
+
+### Semantic HTML Elements
+
+```tsx
+import { Text } from '@delightui/components';
+
+function SemanticElementsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Text as="h1" type="Heading1">Rendered as H1</Text>
+      <Text as="h2" type="Heading2">Rendered as H2</Text>
+      <Text as="h3" type="Heading3">Rendered as H3</Text>
+      <Text as="p" type="BodyLarge">Rendered as Paragraph</Text>
+      <Text as="span" type="BodyMedium">Rendered as Span</Text>
+      
+      <div>
+        <Text as="strong" weight="Bold">Strong element</Text> within normal text
+      </div>
+      
+      <div>
+        <Text as="em" italic>Emphasized element</Text> within normal text
+      </div>
+    </div>
+  );
+}
+```
+
+### Complex Text Combinations
+
+```tsx
+import { Text } from '@delightui/components';
+
+function ComplexTextExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <Text 
+        type="Heading2" 
+        weight="Bold" 
+        decoration="Underline"
+        transform="Capitalize"
+      >
+        complex heading with multiple styles
+      </Text>
+
+      <Text 
+        type="BodyLarge" 
+        weight="Medium" 
+        italic
+        decoration="None"
+      >
+        This is a medium-weight, italic body text that demonstrates multiple styling options combined together.
+      </Text>
+
+      <div style={{ width: '300px', border: '1px solid #ccc', padding: '12px' }}>
+        <Text 
+          type="BodySmall" 
+          weight="SemiBold"
+          transform="UpperCase"
+          ellipsis
+        >
+          This uppercase text will be truncated with ellipsis when it overflows the container width
+        </Text>
+      </div>
+
+      <Text 
+        type="Heading4" 
+        weight="Light"
+        decoration="Strikethrough"
+        transform="LowerCase"
+      >
+        LIGHT WEIGHT HEADING WITH STRIKETHROUGH
+      </Text>
+    </div>
+  );
+}
+```
+
+### Article Layout Example
+
+```tsx
+import { Text, List, ListItem } from '@delightui/components';
+
+function ArticleLayoutExample() {
+  return (
+    <article style={{ maxWidth: '600px', lineHeight: 1.6 }}>
+      <Text as="h1" type="Heading1" weight="Bold" style={{ marginBottom: '8px' }}>
+        The Future of Web Development
+      </Text>
+      
+      <Text as="p" type="BodySmall" weight="Medium" style={{ marginBottom: '24px', color: '#666' }}>
+        Published on March 15, 2024 by John Doe
+      </Text>
+
+      <Text as="h2" type="Heading3" weight="SemiBold" style={{ marginBottom: '12px', marginTop: '24px' }}>
+        Introduction
+      </Text>
+      
+      <Text as="p" type="BodyMedium" style={{ marginBottom: '16px' }}>
+        Web development continues to evolve at a rapid pace, with new technologies and frameworks 
+        emerging regularly. In this article, we'll explore the trends that are shaping the future 
+        of how we build web applications.
+      </Text>
+
+      <Text as="h2" type="Heading3" weight="SemiBold" style={{ marginBottom: '12px', marginTop: '24px' }}>
+        Key Technologies
+      </Text>
+      
+      <Text as="p" type="BodyMedium" style={{ marginBottom: '12px' }}>
+        Several technologies are driving innovation in web development:
+      </Text>
+
+      <List style={{ marginBottom: '16px' }}>
+        <ListItem><Text as="span" type="BodyMedium" weight="Medium">React and Vue.js</Text> - Component-based frameworks</ListItem>
+        <ListItem><Text as="span" type="BodyMedium" weight="Medium">TypeScript</Text> - Type-safe JavaScript development</ListItem>
+        <ListItem><Text as="span" type="BodyMedium" weight="Medium">WebAssembly</Text> - High-performance web applications</ListItem>
+      </List>
+
+      <Text as="blockquote" type="BodyLarge" italic style={{ 
+        borderLeft: '4px solid #007bff', 
+        paddingLeft: '16px', 
+        margin: '20px 0',
+        color: '#555'
+      }}>
+        "The future of web development lies in creating more interactive, performant, and accessible experiences for users across all devices."
+      </Text>
+
+      <Text as="h2" type="Heading3" weight="SemiBold" style={{ marginBottom: '12px', marginTop: '24px' }}>
+        Conclusion
+      </Text>
+      
+      <Text as="p" type="BodyMedium" style={{ marginBottom: '16px' }}>
+        As we look ahead, the emphasis on <Text as="strong" weight="Bold">performance</Text>, 
+        <Text as="em" italic> accessibility</Text>, and <Text decoration="Underline">user experience</Text> will 
+        continue to drive innovation in web development practices and tools.
+      </Text>
+    </article>
+  );
+}
+```
+
+### Status and Alert Text
+
+```tsx
+import { Text } from '@delightui/components';
+
+function StatusTextExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <div style={{ padding: '12px', backgroundColor: '#d4edda', borderRadius: '4px' }}>
+        <Text weight="Bold" style={{ color: '#155724' }}>
+          Success: Operation completed successfully
+        </Text>
+      </div>
+
+      <div style={{ padding: '12px', backgroundColor: '#f8d7da', borderRadius: '4px' }}>
+        <Text weight="Bold" style={{ color: '#721c24' }}>
+          Error: Something went wrong
+        </Text>
+      </div>
+
+      <div style={{ padding: '12px', backgroundColor: '#fff3cd', borderRadius: '4px' }}>
+        <Text weight="Bold" style={{ color: '#856404' }}>
+          Warning: Please review your input
+        </Text>
+      </div>
+
+      <div style={{ padding: '12px', backgroundColor: '#d1ecf1', borderRadius: '4px' }}>
+        <Text weight="Bold" style={{ color: '#0c5460' }}>
+          Info: Additional information available
+        </Text>
+      </div>
+    </div>
+  );
+}
+```
+
+### Card Content Example
+
+```tsx
+import { Text, Button } from '@delightui/components';
+
+function CardContentExample() {
+  return (
+    <div style={{ 
+      border: '1px solid #ccc', 
+      borderRadius: '8px', 
+      padding: '20px',
+      maxWidth: '350px',
+      backgroundColor: '#fff'
+    }}>
+      <Text as="h3" type="Heading4" weight="Bold" style={{ marginBottom: '8px' }}>
+        Product Title
+      </Text>
+      
+      <Text type="BodySmall" weight="Medium" style={{ color: '#666', marginBottom: '12px' }}>
+        Category: Electronics
+      </Text>
+      
+      <Text type="BodyMedium" style={{ marginBottom: '16px', lineHeight: 1.5 }}>
+        This is a detailed description of the product that explains its features, 
+        benefits, and why customers should consider purchasing it.
+      </Text>
+      
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '16px' }}>
+        <Text type="Heading4" weight="Bold" style={{ color: '#007bff' }}>
+          $299.99
+        </Text>
+        <Text type="BodySmall" decoration="Strikethrough" style={{ color: '#999' }}>
+          $399.99
+        </Text>
+      </div>
+      
+      <Text type="BodySmall" weight="SemiBold" transform="UpperCase" style={{ 
+        color: '#28a745', 
+        marginBottom: '16px'
+      }}>
+        In Stock
+      </Text>
+      
+      <Button style={{ width: '100%' }}>
+        Add to Cart
+      </Button>
+    </div>
+  );
+}
+```
+
+### Form Labels and Help Text
+
+```tsx
+import { Text, Input, Button, FormField, Form } from '@delightui/components';
+
+function FormTextExample() {
+  return (
+    <Form onSubmit={(data) => console.log(data)}>
+      <FormField name="username" label="Username" required>
+        <Input placeholder="Enter your username" />
+      </FormField>
+      
+      <div style={{ marginTop: '8px', marginBottom: '16px' }}>
+        <Text type="BodySmall" style={{ color: '#666' }}>
+          Username must be 3-20 characters long and contain only letters, numbers, and underscores.
+        </Text>
+      </div>
+
+      <FormField name="email" label="Email Address" required>
+        <Input inputType="Email" placeholder="Enter your email" />
+      </FormField>
+      
+      <div style={{ marginTop: '8px', marginBottom: '16px' }}>
+        <Text type="BodySmall" style={{ color: '#666' }}>
+          We'll never share your email with anyone else.
+        </Text>
+      </div>
+
+      <Text type="BodySmall" style={{ color: '#666', marginBottom: '16px' }}>
+        By clicking "Sign Up", you agree to our{' '}
+        <Text as="a" decoration="Underline" style={{ color: '#007bff' }}>
+          Terms of Service
+        </Text>{' '}
+        and{' '}
+        <Text as="a" decoration="Underline" style={{ color: '#007bff' }}>
+          Privacy Policy
+        </Text>.
+      </Text>
+
+      <Button type="submit">Sign Up</Button>
+    </Form>
+  );
+}
+```