@lumaui/angular 0.1.0

package/src/lib/card/card.docs.md

@@ -0,0 +1,452 @@
+---
+name: Card
+type: component
+selector: luma-card
+category: Layout
+description: Flexible, composable container for grouping related content with multiple visual variants following Neo-Minimal design principles.
+inputs:
+  - name: lmVariant
+    type: "'default' | 'shadow' | 'nested' | 'preview'"
+    default: "'default'"
+    description: Card visual style variant
+directives:
+  - name: lumaCardHeader
+    selector: '[lumaCardHeader]'
+    description: Container for card header content (title and description)
+  - name: lumaCardTitle
+    selector: '[lumaCardTitle]'
+    description: Card title with customizable size
+    inputs:
+      - name: lmSize
+        type: "'small' | 'normal' | 'large'"
+        default: "'normal'"
+        description: Title size variant
+  - name: lumaCardDescription
+    selector: '[lumaCardDescription]'
+    description: Card description text with customizable size
+    inputs:
+      - name: lmSize
+        type: "'small' | 'normal' | 'large'"
+        default: "'normal'"
+        description: Description size variant
+  - name: lumaCardContent
+    selector: '[lumaCardContent]'
+    description: Container for card main content
+tokens:
+  # Legacy (gradient)
+  - name: --luma-card-background
+    value: oklch(1 0 0)
+    description: Legacy card background color
+  - name: --luma-card-gradient-from
+    value: oklch(0.92 0.005 0 / 0.6)
+    description: Gradient border start color
+  - name: --luma-card-gradient-to
+    value: oklch(0.96 0.003 0 / 0.6)
+    description: Gradient border end color
+  - name: --luma-card-padding
+    value: 1.5rem
+    description: Card internal padding
+  - name: --luma-card-box-shadow
+    value: 0px 2px 0 0px #e4e4e4
+    description: Legacy card shadow
+  # Shadow variant
+  - name: --luma-card-shadow-background
+    value: oklch(1 0 0)
+    description: Shadow card background
+  - name: --luma-card-shadow-border
+    value: oklch(0.92 0.008 265)
+    description: Shadow card border
+  - name: --luma-card-shadow-shadow
+    value: 0 8px 24px oklch(0.22 0.01 265 / 0.06)
+    description: Shadow card shadow
+  - name: --luma-card-shadow-radius
+    value: 16px
+    description: Shadow card border radius
+  # Nested variant
+  - name: --luma-card-nested-background
+    value: oklch(0.98 0.005 265)
+    description: Nested card background
+  - name: --luma-card-nested-border
+    value: oklch(0.92 0.008 265)
+    description: Nested card border
+  - name: --luma-card-nested-radius
+    value: 12px
+    description: Nested card border radius
+  # Preview variant
+  - name: --luma-card-preview-background
+    value: oklch(0.98 0.005 265)
+    description: Preview card background
+  - name: --luma-card-preview-border
+    value: oklch(0.92 0.008 265)
+    description: Preview card border
+  - name: --luma-card-preview-radius
+    value: 12px
+    description: Preview card border radius
+---
+
+# Card
+
+## Purpose
+
+The Card component provides a flexible, composable container for grouping related content with multiple visual variants that follow Neo-Minimal design principles. Built using a compositional architecture with semantic directives.
+
+## Architecture
+
+The Card uses a **compositional design** with a main component and four semantic directives:
+
+- `<luma-card>`: Main container with configurable visual variant
+- `[lumaCardHeader]`: Structural directive for header region with spacing
+- `[lumaCardTitle]`: Title with size variants
+- `[lumaCardDescription]`: Subtitle/description with size variants
+- `[lumaCardContent]`: Semantic marker for main content region
+
+## Component API
+
+### CardComponent
+
+- `lmVariant`: 'default' | 'shadow' | 'nested' | 'preview' - Card visual style
+  - **default**: Gradient border wrapper style (default)
+  - **shadow**: Elevated card with subtle shadow for primary content
+  - **nested**: Subtle background for sections within cards
+  - **preview**: For documentation examples and code previews
+
+### CardTitleDirective
+
+- `lmSize`: 'small' | 'normal' | 'large' - Title size variant
+  - **small**: `text-sm` - Compact cards or secondary information
+  - **normal**: `text-lg` (default) - Standard card titles
+  - **large**: `text-2xl` - Hero cards or primary emphasis
+
+### CardDescriptionDirective
+
+- `lmSize`: 'small' | 'normal' | 'large' - Description size variant
+  - **small**: `text-xs` - Compact cards or tertiary information
+  - **normal**: `text-sm` (default) - Standard descriptions
+  - **large**: `text-base` - Emphasis or standalone descriptions
+
+### CardHeaderDirective
+
+No inputs - provides structural spacing (`mb-4`).
+
+### CardContentDirective
+
+No inputs - semantic marker with no styles applied for maximum flexibility.
+
+## Card Variants
+
+The Card component supports four visual variants via the `lmVariant` input:
+
+### Default
+
+Gradient border wrapper style with distinctive "light as structure" effect (default):
+
+```html
+<luma-card>
+  <div lumaCardHeader>
+    <h3 lumaCardTitle>Gradient Card</h3>
+    <p lumaCardDescription>Default card with gradient border</p>
+  </div>
+  <div lumaCardContent>
+    <p>Content with gradient wrapper styling.</p>
+  </div>
+</luma-card>
+```
+
+### Shadow
+
+Elevated card with shadow, ideal for primary content areas and main UI elements:
+
+```html
+<luma-card lmVariant="shadow">
+  <div lumaCardHeader>
+    <h3 lumaCardTitle>Shadow Card</h3>
+    <p lumaCardDescription>Elevated card with subtle shadow</p>
+  </div>
+  <div lumaCardContent>
+    <p>Primary content with clean, elevated appearance.</p>
+  </div>
+</luma-card>
+```
+
+### Nested
+
+Subtle background for sections within other containers or cards:
+
+```html
+<luma-card lmVariant="shadow">
+  <div lumaCardHeader>
+    <h3 lumaCardTitle>Parent Card</h3>
+  </div>
+  <div lumaCardContent>
+    <!-- Nested card inside -->
+    <luma-card lmVariant="nested">
+      <div lumaCardContent>
+        <p>Nested content with subtle differentiation.</p>
+      </div>
+    </luma-card>
+  </div>
+</luma-card>
+```
+
+### Preview
+
+For documentation examples, code showcases, and component previews:
+
+```html
+<luma-card lmVariant="preview">
+  <div lumaCardContent>
+    <div class="flex items-center justify-center p-8">
+      <!-- Component preview -->
+      <button lumaButton lmVariant="primary">Preview Button</button>
+    </div>
+  </div>
+</luma-card>
+```
+
+## Usage Examples
+
+### Basic Card
+
+```html
+<luma-card>
+  <div lumaCardHeader>
+    <h3 lumaCardTitle>Card Title</h3>
+    <p lumaCardDescription>This is a description of the card content.</p>
+  </div>
+  <div lumaCardContent>
+    <p>Main content goes here.</p>
+  </div>
+</luma-card>
+```
+
+### Stats Card
+
+```html
+<luma-card lmVariant="shadow">
+  <div lumaCardHeader>
+    <h3 lumaCardTitle lmSize="small">Total Revenue</h3>
+  </div>
+  <div lumaCardContent>
+    <p class="text-3xl font-bold">$45,231.89</p>
+    <p class="text-xs lm-text-secondary">+20.1% from last month</p>
+  </div>
+</luma-card>
+```
+
+### Minimal Card (No Header)
+
+```html
+<luma-card lmVariant="nested">
+  <div lumaCardContent>
+    <p>Simple content without header or title.</p>
+  </div>
+</luma-card>
+```
+
+### Card with Custom Content
+
+```html
+<luma-card lmVariant="shadow">
+  <div lumaCardHeader>
+    <h3 lumaCardTitle>User Profile</h3>
+    <p lumaCardDescription>Manage your account settings</p>
+  </div>
+  <div lumaCardContent>
+    <div class="flex items-center gap-4">
+      <img src="avatar.jpg" alt="Avatar" class="w-12 h-12 rounded-full" />
+      <div>
+        <p class="font-medium">John Doe</p>
+        <p class="text-sm lm-text-secondary">john@example.com</p>
+      </div>
+    </div>
+  </div>
+</luma-card>
+```
+
+### Dashboard Layout with Mixed Variants
+
+```html
+<!-- Main content card -->
+<luma-card lmVariant="shadow">
+  <div lumaCardHeader>
+    <h2 lumaCardTitle lmSize="large">Dashboard</h2>
+  </div>
+  <div lumaCardContent>
+    <div class="grid grid-cols-3 gap-4">
+      <!-- Nested stat cards -->
+      <luma-card lmVariant="nested">
+        <div lumaCardContent>
+          <p class="text-xs lm-text-secondary">Users</p>
+          <p class="text-2xl font-bold">1,234</p>
+        </div>
+      </luma-card>
+      <luma-card lmVariant="nested">
+        <div lumaCardContent>
+          <p class="text-xs lm-text-secondary">Revenue</p>
+          <p class="text-2xl font-bold">$12.5k</p>
+        </div>
+      </luma-card>
+      <luma-card lmVariant="nested">
+        <div lumaCardContent>
+          <p class="text-xs lm-text-secondary">Growth</p>
+          <p class="text-2xl font-bold">+15%</p>
+        </div>
+      </luma-card>
+    </div>
+  </div>
+</luma-card>
+```
+
+## Gradient Border Technique
+
+The **default** variant uses a distinctive gradient border technique that aligns with Neo-Minimal principles:
+
+**How it works:**
+
+1. Outer wrapper has `p-[1px]` padding + `bg-gradient-to-b` gradient
+2. Inner content has matching border-radius (slightly smaller for visual precision)
+3. Gradient creates a subtle "light as structure" effect instead of hard borders
+
+**Visual effect:**
+
+- Light mode: Subtle gradient from light gray to slightly darker gray
+- Dark mode: Inverted gradient for depth perception
+- No hard borders, shadows, or mechanical separators
+- Depth is perceived through luminosity differences
+
+This technique exemplifies the Neo-Minimal principle: **"Light as Structure, not decoration"**.
+
+## Customizing
+
+The card appearance can be customized using CSS variables defined in `@lumaui/tokens`.
+
+### Override Globally
+
+```css
+/* In your global styles.css */
+:root {
+  --luma-card-shadow-background: #ffffff;
+  --luma-card-shadow-shadow: 0 4px 12px rgba(0, 0, 0, 0.05);
+  --luma-card-padding: 24px;
+}
+```
+
+### Override Per Theme
+
+```css
+/* Light mode */
+:root {
+  --luma-card-shadow-background: #fafafa;
+}
+
+/* Dark mode */
+.dark {
+  --luma-card-shadow-background: oklch(0.18 0.005 265);
+  --luma-card-nested-background: oklch(0.2 0.005 265);
+}
+```
+
+### Override Per Component
+
+```css
+/* Cards in sidebar - more compact */
+.sidebar {
+  --luma-card-padding: 16px;
+}
+
+/* Cards in hero section - more prominent shadow */
+.hero {
+  --luma-card-shadow-shadow: 0 12px 32px oklch(0.22 0.01 265 / 0.1);
+}
+```
+
+## Neo-Minimal Principles
+
+The Card design embodies core Neo-Minimal values:
+
+- **Visual Silence**: Subtle borders and shadows, never demands attention
+- **Light as Structure**: Luminosity differences create depth without heavy shadows
+- **Functional Whitespace**: Generous padding (`24px` default) creates hierarchy
+- **Form & Geometry**: Rounded corners (`16px` product, `12px` nested) feel organic
+- **Organic Geometry**: Soft edges flow naturally, avoiding hard mechanical lines
+- **Editorial Color**: No brand colors in structure - neutral tones only
+- **Compositional Architecture**: Directives compose semantically, not through rigid templates
+
+## Accessibility
+
+- **Semantic HTML**: Proper heading hierarchy with `<h2>`, `<h3>`, `<h4>` elements
+- **Color contrast**: Background and text meet WCAG AA 4.5:1 minimum
+- **Readable typography**: Generous line-height and spacing for comfortable reading
+- **Theme support**: Both light and dark modes maintain accessibility standards
+- **Flexible structure**: No enforced heading levels - adapt to your document outline
+
+**Accessibility Notes:**
+
+- Use appropriate heading levels (`<h2>`, `<h3>`, etc.) with `lumaCardTitle` directive
+- Ensure descriptions provide meaningful context for screen reader users
+- Maintain logical heading hierarchy in your document
+
+## Implementation Notes
+
+- Uses Angular 20+ signal-based computed values (`computed()`)
+- Styled with Tailwind CSS v4 utilities referencing design tokens with `lm-` prefix
+- Type-safe variant types exported: `CardVariant`, `CardTitleVariants`, `CardDescriptionVariants`
+- OnPush change detection for optimal performance
+- Compositional architecture allows flexible content projection
+
+## When to Use Each Variant
+
+| Variant   | Use Case                                            |
+| --------- | --------------------------------------------------- |
+| `default` | Default styling, distinctive gradient border effect |
+| `shadow`  | Primary content, main UI cards, elevated sections   |
+| `nested`  | Sections within cards, grouped content, stat blocks |
+| `preview` | Documentation examples, component showcases         |
+
+**Avoid using Card when:**
+
+- Content doesn't need visual separation (use whitespace instead)
+- Creating overly nested card-within-card layouts (violates visual silence)
+- Every element needs a container (over-containerization)
+- A simple list would suffice
+
+**Remember:** Per Neo-Minimal principles, "If an element can be removed without functional or semantic loss, it shouldn't exist."
+
+## Design Token Reference
+
+### Legacy Gradient Tokens
+
+| Token                       | Default Value               | Purpose               |
+| --------------------------- | --------------------------- | --------------------- |
+| `--luma-card-background`    | `oklch(1 0 0)`              | Inner card background |
+| `--luma-card-gradient-from` | `oklch(0.92 0.005 0 / 0.6)` | Top gradient edge     |
+| `--luma-card-gradient-to`   | `oklch(0.96 0.003 0 / 0.6)` | Bottom gradient edge  |
+| `--luma-card-padding`       | `1.5rem`                    | Inner content padding |
+| `--luma-card-box-shadow`    | `0px 2px 0 0px #e4e4e4`     | Legacy shadow         |
+
+### Shadow Variant Tokens
+
+| Token                           | Default Value                            | Purpose         |
+| ------------------------------- | ---------------------------------------- | --------------- |
+| `--luma-card-shadow-background` | `oklch(1 0 0)`                           | Card background |
+| `--luma-card-shadow-border`     | `oklch(0.92 0.008 265)`                  | Border color    |
+| `--luma-card-shadow-shadow`     | `0 8px 24px oklch(0.22 0.01 265 / 0.06)` | Soft elevation  |
+| `--luma-card-shadow-radius`     | `16px`                                   | Border radius   |
+
+### Nested Variant Tokens
+
+| Token                           | Default Value           | Purpose           |
+| ------------------------------- | ----------------------- | ----------------- |
+| `--luma-card-nested-background` | `oklch(0.98 0.005 265)` | Subtle background |
+| `--luma-card-nested-border`     | `oklch(0.92 0.008 265)` | Border color      |
+| `--luma-card-nested-radius`     | `12px`                  | Border radius     |
+
+### Preview Variant Tokens
+
+| Token                            | Default Value           | Purpose            |
+| -------------------------------- | ----------------------- | ------------------ |
+| `--luma-card-preview-background` | `oklch(0.98 0.005 265)` | Preview background |
+| `--luma-card-preview-border`     | `oklch(0.92 0.008 265)` | Border color       |
+| `--luma-card-preview-radius`     | `12px`                  | Border radius      |
+
+**Note:** Dark theme values are defined in `card.dark.json` and automatically applied via `.dark` selector.

package/src/lib/card/index.ts

@@ -0,0 +1,19 @@
+// Main Card component
+export * from './card.component';
+
+// Card compositional directives
+export * from './card-title.directive';
+export * from './card-description.directive';
+export * from './card-header.directive';
+export * from './card-content.directive';
+
+// Re-export types from core for convenience
+export type {
+  CardVariants,
+  CardContentVariants,
+  CardTitleVariants,
+  CardDescriptionVariants,
+  CardVariant,
+  CardTitleSize,
+  CardDescriptionSize,
+} from '@lumaui/core';

package/src/test-setup.ts

@@ -0,0 +1,5 @@
+import '@angular/compiler';
+import '@analogjs/vitest-angular/setup-snapshots';
+import { setupTestBed } from '@analogjs/vitest-angular/setup-testbed';
+
+setupTestBed();