fragment-headless-sdk 2.1.4 → 2.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/components/Announcement/CountdownTimer.js +3 -1
- package/dist/types/announcement.d.ts +4 -2
- package/dist/types/hero.d.ts +5 -3
- package/dist/types/styling.d.ts +0 -13
- package/dist/utils/styling.js +2 -14
- package/package.json +1 -1
- package/readme.md +15 -620
- package/dist/styles/fragment-sdk.css +0 -31
|
@@ -45,7 +45,9 @@ export default function CountdownTimer({ content, }) {
|
|
|
45
45
|
}, styling, "countdownLabel");
|
|
46
46
|
const labelAttributes = mergeSlotAttributes(styling, "countdownLabel");
|
|
47
47
|
const separatorClass = mergeSlotClasses("text-xl font-semibold -mt-4", styling, "countdownSeparator");
|
|
48
|
-
const separatorStyle = mergeSlotStyles(
|
|
48
|
+
const separatorStyle = mergeSlotStyles({
|
|
49
|
+
color: digitTextColor,
|
|
50
|
+
}, styling, "countdownSeparator");
|
|
49
51
|
const separatorAttributes = mergeSlotAttributes(styling, "countdownSeparator");
|
|
50
52
|
const renderBlock = (value, label) => (React.createElement("div", { className: blockClass, style: blockStyle, ...(blockAttributes ?? {}) },
|
|
51
53
|
React.createElement("div", { className: "flex" }, value.split("").map((digit, i) => (React.createElement("span", { key: i, className: digitClass, style: digitStyle, ...(digitAttributes ?? {}) }, digit)))),
|
|
@@ -21,8 +21,10 @@ export interface IAnnouncement {
|
|
|
21
21
|
name: string;
|
|
22
22
|
status: AnnouncementStatus;
|
|
23
23
|
content: IAnnouncementContent | null;
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
active_start_date: string | null;
|
|
25
|
+
active_end_date: string | null;
|
|
26
|
+
created_at: string | null;
|
|
27
|
+
updated_at: string | null;
|
|
26
28
|
views_count: number;
|
|
27
29
|
clicks_count: number;
|
|
28
30
|
}
|
package/dist/types/hero.d.ts
CHANGED
|
@@ -22,11 +22,13 @@ export interface IHero {
|
|
|
22
22
|
shop: string;
|
|
23
23
|
name: string;
|
|
24
24
|
type: HeroType;
|
|
25
|
-
page: ShopPage["handle"];
|
|
25
|
+
page: ShopPage["handle"] | null;
|
|
26
26
|
status: HeroStatus;
|
|
27
27
|
content: IHeroContent | null;
|
|
28
|
-
|
|
29
|
-
|
|
28
|
+
active_start_date: string | null;
|
|
29
|
+
active_end_date: string | null;
|
|
30
|
+
created_at: string | null;
|
|
31
|
+
updated_at: string | null;
|
|
30
32
|
views_count: number;
|
|
31
33
|
clicks_count: number;
|
|
32
34
|
}
|
package/dist/types/styling.d.ts
CHANGED
|
@@ -63,19 +63,6 @@ export interface IFragmentStyling {
|
|
|
63
63
|
* Structured design tokens for consistent theming.
|
|
64
64
|
*/
|
|
65
65
|
tokens?: IFragmentTokens;
|
|
66
|
-
/**
|
|
67
|
-
* Legacy flat token support for backward compatibility.
|
|
68
|
-
* @deprecated Use structured tokens instead.
|
|
69
|
-
*/
|
|
70
|
-
legacyTokens?: Record<string, string>;
|
|
71
|
-
/**
|
|
72
|
-
* Theme variant (light, dark, brand, etc.).
|
|
73
|
-
*/
|
|
74
|
-
theme?: "light" | "dark" | "brand" | "minimal" | "bold" | string;
|
|
75
|
-
/**
|
|
76
|
-
* Component variant for different styles of the same component.
|
|
77
|
-
*/
|
|
78
|
-
variant?: "default" | "outlined" | "ghost" | "solid" | "gradient" | string;
|
|
79
66
|
/**
|
|
80
67
|
* Global CSS variables to apply to the component root.
|
|
81
68
|
*/
|
package/dist/utils/styling.js
CHANGED
|
@@ -260,10 +260,6 @@ export function resolveToken(styling, token, fallback) {
|
|
|
260
260
|
}
|
|
261
261
|
}
|
|
262
262
|
}
|
|
263
|
-
// Fall back to legacy tokens
|
|
264
|
-
if (styling.legacyTokens && token in styling.legacyTokens) {
|
|
265
|
-
return styling.legacyTokens[token];
|
|
266
|
-
}
|
|
267
263
|
return fallback;
|
|
268
264
|
}
|
|
269
265
|
export function resolveTokenByCategory(styling, category, token, fallback) {
|
|
@@ -278,16 +274,8 @@ export function resolveTokenByCategory(styling, category, token, fallback) {
|
|
|
278
274
|
return fallback;
|
|
279
275
|
}
|
|
280
276
|
export function getThemeClasses(styling) {
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
const classes = [];
|
|
284
|
-
if (styling.theme) {
|
|
285
|
-
classes.push(`theme-${styling.theme}`);
|
|
286
|
-
}
|
|
287
|
-
if (styling.variant) {
|
|
288
|
-
classes.push(`variant-${styling.variant}`);
|
|
289
|
-
}
|
|
290
|
-
return classes.join(" ");
|
|
277
|
+
// Theme and variant system has been removed
|
|
278
|
+
return "";
|
|
291
279
|
}
|
|
292
280
|
export function generateCSS(styling) {
|
|
293
281
|
if (!styling)
|
package/package.json
CHANGED
package/readme.md
CHANGED
|
@@ -2,44 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
The official SDK for integrating with Fragment-Shopify CMS. Provides React components, TypeScript types, and utilities for rendering published sections in headless Shopify storefronts.
|
|
4
4
|
|
|
5
|
-
## ✨ What's New
|
|
5
|
+
## ✨ What's New
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
⚡ **Enhanced Announcement Layouts** - Countdown timers can now display alongside buttons
|
|
7
|
+
**v2.1.4** - Countdown timer enhancements and improved announcement layouts
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
⚡ **Request Deduplication** - Intelligent request deduplication prevents identical concurrent API calls
|
|
13
|
-
🚀 **Enhanced Caching** - Improved caching strategy with 60-second revalidation for better performance
|
|
14
|
-
🔧 **Optimized Fetching** - Consistent parameter handling and smarter cache key generation
|
|
15
|
-
🛡️ **Anti-Spam Protection** - Built-in protection against redundant API requests
|
|
16
|
-
|
|
17
|
-
### Previous Release (v2.1.2)
|
|
18
|
-
|
|
19
|
-
📚 **Enhanced Documentation** - Comprehensive documentation updates highlighting new click tracking features
|
|
20
|
-
📖 **Better Examples** - Improved usage examples and feature descriptions
|
|
21
|
-
🎯 **Feature Highlights** - Clear documentation of the enhanced click tracking system
|
|
22
|
-
|
|
23
|
-
### Previous Release (v2.1.1)
|
|
24
|
-
|
|
25
|
-
🎯 **Enhanced Click Tracking System** - Improved click tracking architecture with better user experience
|
|
26
|
-
⚡ **Direct Navigation** - Users go directly to destinations without redirect delays
|
|
27
|
-
🔗 **Separated Tracking** - Button destinations and click tracking are now handled separately
|
|
28
|
-
🛠️ **Better Performance** - Non-blocking click tracking that doesn't delay navigation
|
|
29
|
-
|
|
30
|
-
### Previous Release (v2.1.0)
|
|
31
|
-
|
|
32
|
-
🎨 **Enhanced Hero Styling System** - New hero resolvers utility with advanced typography, positioning, and layout controls
|
|
33
|
-
🔤 **Advanced Typography** - Built-in font family support with granular control over sizes and line heights
|
|
34
|
-
📐 **Flexible Layout Controls** - Content positioning (left/center/right), width management, and height configuration
|
|
35
|
-
🎯 **Developer Experience** - Enhanced TypeScript interfaces and utility functions for better development workflow
|
|
36
|
-
|
|
37
|
-
### Previous Major Release (v2.0.0)
|
|
38
|
-
|
|
39
|
-
🎨 **Revolutionary Styling System** - Complete overhaul with advanced theming, responsive design, and scalable architecture
|
|
40
|
-
🏗️ **Component-Specific Types** - Enhanced type safety with dedicated slot interfaces
|
|
41
|
-
🚀 **Performance Optimized** - Caching and optimizations for production-ready performance
|
|
42
|
-
🎯 **Future-Proof Architecture** - Built to scale with any number of components and styling requirements
|
|
9
|
+
> See [CHANGELOG.md](./docs/CHANGELOG.md) for full release history
|
|
43
10
|
|
|
44
11
|
---
|
|
45
12
|
|
|
@@ -64,7 +31,7 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
|
|
|
64
31
|
- ✅ **Data Fetching**: Built-in utilities to fetch sections from Fragment-Shopify API
|
|
65
32
|
- ✅ **React Components**: Pre-built Hero and Announcement components with responsive design
|
|
66
33
|
- ✅ **TypeScript Support**: Full type definitions for all components and data structures
|
|
67
|
-
- ✅ **Multiple Announcement Types**: Standard, marquee, and countdown
|
|
34
|
+
- ✅ **Multiple Announcement Types**: Standard, marquee, and countdown announcements
|
|
68
35
|
- ✅ **Hero Sections**: Desktop/mobile responsive hero components with video support
|
|
69
36
|
- ✅ **Advanced Click Tracking**: Separated tracking and navigation for optimal user experience
|
|
70
37
|
|
|
@@ -73,10 +40,9 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
|
|
|
73
40
|
- 🎨 **Structured Design Tokens**: Organized color, spacing, typography, and effect tokens
|
|
74
41
|
- 📱 **Responsive Styling**: Breakpoint-specific overrides (sm, md, lg, xl, 2xl)
|
|
75
42
|
- 🎭 **State-Based Styling**: Hover, active, focus, disabled, and loading states
|
|
76
|
-
- 🎯 **
|
|
43
|
+
- 🎯 **Design Token System**: Structured tokens for consistent styling
|
|
77
44
|
- 🔧 **Component-Specific Slots**: Type-safe styling for individual component parts
|
|
78
45
|
- ⚡ **Performance Optimized**: Caching and memoization for optimal performance
|
|
79
|
-
- 🔄 **Legacy Compatibility**: Seamless migration path from v1.x styling
|
|
80
46
|
- 🎪 **CSS-in-JS Support**: Integration with styled-components, emotion, etc.
|
|
81
47
|
|
|
82
48
|
### Hero Resolvers System (v2.1+)
|
|
@@ -86,7 +52,6 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
|
|
|
86
52
|
- 🎨 **Smart Color Resolution**: Intelligent fallback handling for color tokens
|
|
87
53
|
- 🛠️ **Utility Functions**: Helper functions for class joining, text rendering, and style resolution
|
|
88
54
|
- 📝 **Type Safety**: Enhanced TypeScript interfaces for all styling options
|
|
89
|
-
- 🔄 **Backward Compatible**: Works seamlessly with existing Hero implementations
|
|
90
55
|
|
|
91
56
|
### Request Deduplication & Performance System (v2.1.3+)
|
|
92
57
|
|
|
@@ -264,10 +229,6 @@ const heroContent = {
|
|
|
264
229
|
|
|
265
230
|
// Advanced styling configuration
|
|
266
231
|
styling: {
|
|
267
|
-
// Theme and variant
|
|
268
|
-
theme: "dark",
|
|
269
|
-
variant: "gradient",
|
|
270
|
-
|
|
271
232
|
// Structured design tokens
|
|
272
233
|
tokens: {
|
|
273
234
|
colors: {
|
|
@@ -322,357 +283,7 @@ const heroContent = {
|
|
|
322
283
|
<Hero content={heroContent} />;
|
|
323
284
|
```
|
|
324
285
|
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
## 🎨 Advanced Styling System
|
|
328
|
-
|
|
329
|
-
### Overview
|
|
330
|
-
|
|
331
|
-
The v2.0 styling system provides unprecedented control over component appearance while maintaining backward compatibility.
|
|
332
|
-
|
|
333
|
-
### Key Concepts
|
|
334
|
-
|
|
335
|
-
#### 1. **Structured Design Tokens**
|
|
336
|
-
|
|
337
|
-
Organize your design system with categorized tokens:
|
|
338
|
-
|
|
339
|
-
```typescript
|
|
340
|
-
styling: {
|
|
341
|
-
tokens: {
|
|
342
|
-
colors: {
|
|
343
|
-
primary: "#007bff",
|
|
344
|
-
secondary: "#6c757d",
|
|
345
|
-
background: "#ffffff",
|
|
346
|
-
text: "#333333"
|
|
347
|
-
},
|
|
348
|
-
spacing: {
|
|
349
|
-
xs: "0.25rem",
|
|
350
|
-
sm: "0.5rem",
|
|
351
|
-
md: "1rem",
|
|
352
|
-
lg: "1.5rem",
|
|
353
|
-
xl: "2rem"
|
|
354
|
-
},
|
|
355
|
-
typography: {
|
|
356
|
-
heading: "2.5rem",
|
|
357
|
-
body: "1rem",
|
|
358
|
-
small: "0.875rem"
|
|
359
|
-
},
|
|
360
|
-
transitions: {
|
|
361
|
-
fast: "150ms ease",
|
|
362
|
-
normal: "300ms ease",
|
|
363
|
-
slow: "500ms ease"
|
|
364
|
-
},
|
|
365
|
-
shadows: {
|
|
366
|
-
sm: "0 1px 2px rgba(0,0,0,0.05)",
|
|
367
|
-
md: "0 4px 6px rgba(0,0,0,0.1)",
|
|
368
|
-
lg: "0 10px 15px rgba(0,0,0,0.1)"
|
|
369
|
-
}
|
|
370
|
-
}
|
|
371
|
-
}
|
|
372
|
-
```
|
|
373
|
-
|
|
374
|
-
#### 2. **Component Slots**
|
|
375
|
-
|
|
376
|
-
Target specific parts of components with type-safe slot names:
|
|
377
|
-
|
|
378
|
-
```typescript
|
|
379
|
-
// Announcement component slots
|
|
380
|
-
slots: {
|
|
381
|
-
root: { /* Root container */ },
|
|
382
|
-
inner: { /* Inner wrapper */ },
|
|
383
|
-
marqueeContainer: { /* Marquee wrapper */ },
|
|
384
|
-
announcementText: { /* Text content */ },
|
|
385
|
-
button: { /* Action button */ },
|
|
386
|
-
closeButton: { /* Close button */ }
|
|
387
|
-
}
|
|
388
|
-
|
|
389
|
-
// Hero component slots
|
|
390
|
-
slots: {
|
|
391
|
-
root: { /* Root container */ },
|
|
392
|
-
desktopContainer: { /* Desktop layout */ },
|
|
393
|
-
mobileContainer: { /* Mobile layout */ },
|
|
394
|
-
image: { /* Background image */ },
|
|
395
|
-
title: { /* Hero title */ },
|
|
396
|
-
description: { /* Hero description */ },
|
|
397
|
-
button: { /* CTA button */ }
|
|
398
|
-
}
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
#### 3. **Responsive Design**
|
|
402
|
-
|
|
403
|
-
Apply different styles at different breakpoints:
|
|
404
|
-
|
|
405
|
-
```typescript
|
|
406
|
-
slots: {
|
|
407
|
-
title: {
|
|
408
|
-
className: "text-2xl font-bold",
|
|
409
|
-
responsive: {
|
|
410
|
-
sm: { className: "text-3xl" },
|
|
411
|
-
md: { className: "text-4xl" },
|
|
412
|
-
lg: { className: "text-5xl" },
|
|
413
|
-
xl: { className: "text-6xl" }
|
|
414
|
-
}
|
|
415
|
-
}
|
|
416
|
-
}
|
|
417
|
-
```
|
|
418
|
-
|
|
419
|
-
#### 4. **State-Based Styling**
|
|
420
|
-
|
|
421
|
-
Style components based on interaction states:
|
|
422
|
-
|
|
423
|
-
```typescript
|
|
424
|
-
slots: {
|
|
425
|
-
button: {
|
|
426
|
-
className: "bg-blue-500 text-white px-6 py-3 rounded",
|
|
427
|
-
states: {
|
|
428
|
-
hover: {
|
|
429
|
-
className: "bg-blue-600 shadow-lg",
|
|
430
|
-
style: { transform: "translateY(-2px)" }
|
|
431
|
-
},
|
|
432
|
-
active: { className: "bg-blue-700" },
|
|
433
|
-
disabled: {
|
|
434
|
-
className: "bg-gray-300 cursor-not-allowed",
|
|
435
|
-
attributes: { "aria-disabled": "true" }
|
|
436
|
-
}
|
|
437
|
-
}
|
|
438
|
-
}
|
|
439
|
-
}
|
|
440
|
-
```
|
|
441
|
-
|
|
442
|
-
#### 5. **Theme and Variant System**
|
|
443
|
-
|
|
444
|
-
Apply consistent theming across components:
|
|
445
|
-
|
|
446
|
-
```typescript
|
|
447
|
-
styling: {
|
|
448
|
-
theme: "dark", // "light" | "dark" | "brand" | custom
|
|
449
|
-
variant: "outlined", // "default" | "outlined" | "ghost" | "solid" | custom
|
|
450
|
-
|
|
451
|
-
// Automatic theme classes applied: "theme-dark variant-outlined"
|
|
452
|
-
}
|
|
453
|
-
```
|
|
454
|
-
|
|
455
|
-
### Migration from v1.x
|
|
456
|
-
|
|
457
|
-
The system maintains full backward compatibility:
|
|
458
|
-
|
|
459
|
-
```typescript
|
|
460
|
-
// v1.x style (still works)
|
|
461
|
-
content: {
|
|
462
|
-
bgColor: "#ffffff",
|
|
463
|
-
textColor: "#333333",
|
|
464
|
-
buttonColor: "#007bff"
|
|
465
|
-
}
|
|
466
|
-
|
|
467
|
-
// v2.0+ enhanced style
|
|
468
|
-
content: {
|
|
469
|
-
styling: {
|
|
470
|
-
// Legacy tokens (backward compatible)
|
|
471
|
-
legacyTokens: {
|
|
472
|
-
bgColor: "#ffffff",
|
|
473
|
-
textColor: "#333333",
|
|
474
|
-
buttonColor: "#007bff"
|
|
475
|
-
},
|
|
476
|
-
|
|
477
|
-
// New structured tokens (recommended)
|
|
478
|
-
tokens: {
|
|
479
|
-
colors: {
|
|
480
|
-
background: "#ffffff",
|
|
481
|
-
text: "#333333",
|
|
482
|
-
button: "#007bff"
|
|
483
|
-
}
|
|
484
|
-
}
|
|
485
|
-
}
|
|
486
|
-
}
|
|
487
|
-
```
|
|
488
|
-
|
|
489
|
-
### CSS-in-JS Integration
|
|
490
|
-
|
|
491
|
-
Support for styled-components, emotion, and other CSS-in-JS libraries:
|
|
492
|
-
|
|
493
|
-
```typescript
|
|
494
|
-
slots: {
|
|
495
|
-
button: {
|
|
496
|
-
css: `
|
|
497
|
-
background: linear-gradient(45deg, #007bff, #0056b3);
|
|
498
|
-
border: none;
|
|
499
|
-
border-radius: 8px;
|
|
500
|
-
padding: 12px 24px;
|
|
501
|
-
|
|
502
|
-
&:hover {
|
|
503
|
-
background: linear-gradient(45deg, #0056b3, #004085);
|
|
504
|
-
transform: translateY(-2px);
|
|
505
|
-
}
|
|
506
|
-
`;
|
|
507
|
-
}
|
|
508
|
-
}
|
|
509
|
-
```
|
|
510
|
-
|
|
511
|
-
---
|
|
512
|
-
|
|
513
|
-
## 🎨 Hero Resolvers System (v2.1+)
|
|
514
|
-
|
|
515
|
-
The Hero Resolvers system provides advanced utilities for customizing Hero components with enhanced typography, layout, and styling controls.
|
|
516
|
-
|
|
517
|
-
### Typography Control
|
|
518
|
-
|
|
519
|
-
```typescript
|
|
520
|
-
import { resolveHeroTypography, FontKey } from "fragment-headless-sdk";
|
|
521
|
-
|
|
522
|
-
// Enhanced typography configuration
|
|
523
|
-
const heroContent = {
|
|
524
|
-
title: "Welcome to Our Store",
|
|
525
|
-
description: "Discover amazing products",
|
|
526
|
-
styling: {
|
|
527
|
-
tokens: {
|
|
528
|
-
typography: {
|
|
529
|
-
// Title typography
|
|
530
|
-
titleFont: "montserrat" as FontKey,
|
|
531
|
-
titleFontSize: "text-6xl",
|
|
532
|
-
titleLineHeight: "leading-tight",
|
|
533
|
-
|
|
534
|
-
// Description typography
|
|
535
|
-
descriptionFont: "inter" as FontKey,
|
|
536
|
-
descriptionFontSize: "text-xl",
|
|
537
|
-
descriptionLineHeight: "leading-relaxed",
|
|
538
|
-
},
|
|
539
|
-
},
|
|
540
|
-
},
|
|
541
|
-
};
|
|
542
|
-
|
|
543
|
-
// Resolve typography settings
|
|
544
|
-
const typography = resolveHeroTypography(heroContent);
|
|
545
|
-
```
|
|
546
|
-
|
|
547
|
-
### Layout & Positioning
|
|
548
|
-
|
|
549
|
-
```typescript
|
|
550
|
-
import {
|
|
551
|
-
resolvePosition,
|
|
552
|
-
resolveContentWidthClass,
|
|
553
|
-
resolveHeight,
|
|
554
|
-
} from "fragment-headless-sdk";
|
|
555
|
-
|
|
556
|
-
const heroContent = {
|
|
557
|
-
title: "Centered Hero",
|
|
558
|
-
styling: {
|
|
559
|
-
tokens: {
|
|
560
|
-
layout: {
|
|
561
|
-
position: "center", // "left" | "center" | "right"
|
|
562
|
-
contentWidth: "max-w-4xl", // Tailwind width classes
|
|
563
|
-
height: "min-h-screen", // Custom height classes
|
|
564
|
-
},
|
|
565
|
-
},
|
|
566
|
-
},
|
|
567
|
-
};
|
|
568
|
-
|
|
569
|
-
// Resolve layout settings
|
|
570
|
-
const position = resolvePosition(heroContent); // "center"
|
|
571
|
-
const contentWidth = resolveContentWidthClass(heroContent); // "max-w-4xl"
|
|
572
|
-
const height = resolveHeight(heroContent); // "min-h-screen"
|
|
573
|
-
```
|
|
574
|
-
|
|
575
|
-
### Color Resolution
|
|
576
|
-
|
|
577
|
-
```typescript
|
|
578
|
-
import { resolveHeroColors } from "fragment-headless-sdk";
|
|
579
|
-
|
|
580
|
-
const heroContent = {
|
|
581
|
-
title: "Styled Hero",
|
|
582
|
-
styling: {
|
|
583
|
-
tokens: {
|
|
584
|
-
colors: {
|
|
585
|
-
title: "#ffffff",
|
|
586
|
-
text: "#f0f0f0",
|
|
587
|
-
button: "#007bff",
|
|
588
|
-
buttonText: "#ffffff",
|
|
589
|
-
background: "#1a1a1a",
|
|
590
|
-
},
|
|
591
|
-
},
|
|
592
|
-
},
|
|
593
|
-
};
|
|
594
|
-
|
|
595
|
-
// Resolve colors with intelligent fallbacks
|
|
596
|
-
const colors = resolveHeroColors(heroContent);
|
|
597
|
-
// Returns: { title: "#ffffff", text: "#f0f0f0", buttonBackground: "#007bff", buttonText: "#ffffff", background: "#1a1a1a" }
|
|
598
|
-
```
|
|
599
|
-
|
|
600
|
-
### Built-in Font Families
|
|
601
|
-
|
|
602
|
-
The system includes support for popular web fonts:
|
|
603
|
-
|
|
604
|
-
```typescript
|
|
605
|
-
type FontKey =
|
|
606
|
-
| "roboto"
|
|
607
|
-
| "open-sans"
|
|
608
|
-
| "lato"
|
|
609
|
-
| "montserrat"
|
|
610
|
-
| "poppins"
|
|
611
|
-
| "inter"
|
|
612
|
-
| "nunito-sans"
|
|
613
|
-
| "source-sans-pro";
|
|
614
|
-
```
|
|
615
|
-
|
|
616
|
-
### Utility Functions
|
|
617
|
-
|
|
618
|
-
```typescript
|
|
619
|
-
import { joinClassNames, renderText } from "fragment-headless-sdk";
|
|
620
|
-
|
|
621
|
-
// Safe class name joining
|
|
622
|
-
const classes = joinClassNames("text-xl", "font-bold", null, "text-center");
|
|
623
|
-
// Returns: "text-xl font-bold text-center"
|
|
624
|
-
|
|
625
|
-
// Unified text rendering
|
|
626
|
-
const titleElement = renderText({
|
|
627
|
-
fontSize: "text-4xl",
|
|
628
|
-
lineHeight: "leading-tight",
|
|
629
|
-
text: "Hero Title",
|
|
630
|
-
className: "font-bold",
|
|
631
|
-
color: "#ffffff",
|
|
632
|
-
font: "montserrat",
|
|
633
|
-
});
|
|
634
|
-
```
|
|
635
|
-
|
|
636
|
-
### Complete Example
|
|
637
|
-
|
|
638
|
-
```typescript
|
|
639
|
-
import { Hero } from "fragment-headless-sdk";
|
|
640
|
-
|
|
641
|
-
const advancedHeroContent = {
|
|
642
|
-
title: "Advanced Hero Section",
|
|
643
|
-
description: "With enhanced typography and layout controls",
|
|
644
|
-
buttonText: "Get Started",
|
|
645
|
-
buttonLink: "/signup",
|
|
646
|
-
imageUrl: "https://example.com/hero.jpg",
|
|
647
|
-
|
|
648
|
-
styling: {
|
|
649
|
-
tokens: {
|
|
650
|
-
colors: {
|
|
651
|
-
title: "#ffffff",
|
|
652
|
-
text: "#e2e8f0",
|
|
653
|
-
button: "#3b82f6",
|
|
654
|
-
buttonText: "#ffffff",
|
|
655
|
-
background: "#1e293b",
|
|
656
|
-
},
|
|
657
|
-
typography: {
|
|
658
|
-
titleFont: "montserrat",
|
|
659
|
-
titleFontSize: "text-5xl lg:text-7xl",
|
|
660
|
-
titleLineHeight: "leading-tight",
|
|
661
|
-
descriptionFont: "inter",
|
|
662
|
-
descriptionFontSize: "text-lg lg:text-xl",
|
|
663
|
-
descriptionLineHeight: "leading-relaxed",
|
|
664
|
-
},
|
|
665
|
-
layout: {
|
|
666
|
-
position: "center",
|
|
667
|
-
contentWidth: "max-w-4xl",
|
|
668
|
-
height: "min-h-screen",
|
|
669
|
-
},
|
|
670
|
-
},
|
|
671
|
-
},
|
|
672
|
-
};
|
|
673
|
-
|
|
674
|
-
<Hero content={advancedHeroContent} />;
|
|
675
|
-
```
|
|
286
|
+
> **Advanced Features:** For detailed styling options, see [STYLING.md](./docs/STYLING.md) | For hero customization, see [HERO-RESOLVERS.md](./docs/HERO-RESOLVERS.md)
|
|
676
287
|
|
|
677
288
|
---
|
|
678
289
|
|
|
@@ -823,88 +434,6 @@ interface IAnnouncementContent {
|
|
|
823
434
|
- `closeButton` - Close button
|
|
824
435
|
- `countdown` - Countdown container (countdown type)
|
|
825
436
|
|
|
826
|
-
---
|
|
827
|
-
|
|
828
|
-
## 🎯 Styling Examples
|
|
829
|
-
|
|
830
|
-
### Basic Theme Application
|
|
831
|
-
|
|
832
|
-
```typescript
|
|
833
|
-
const styling = {
|
|
834
|
-
theme: "dark",
|
|
835
|
-
variant: "outlined",
|
|
836
|
-
tokens: {
|
|
837
|
-
colors: {
|
|
838
|
-
background: "#1a1a1a",
|
|
839
|
-
text: "#ffffff",
|
|
840
|
-
button: "#007bff",
|
|
841
|
-
},
|
|
842
|
-
},
|
|
843
|
-
};
|
|
844
|
-
```
|
|
845
|
-
|
|
846
|
-
### Responsive Hero Design
|
|
847
|
-
|
|
848
|
-
```typescript
|
|
849
|
-
const heroStyling = {
|
|
850
|
-
slots: {
|
|
851
|
-
title: {
|
|
852
|
-
className: "font-bold text-center",
|
|
853
|
-
responsive: {
|
|
854
|
-
sm: { className: "text-3xl" },
|
|
855
|
-
md: { className: "text-4xl text-left" },
|
|
856
|
-
lg: { className: "text-6xl" },
|
|
857
|
-
},
|
|
858
|
-
},
|
|
859
|
-
button: {
|
|
860
|
-
className: "px-6 py-3 rounded-lg",
|
|
861
|
-
responsive: {
|
|
862
|
-
md: { className: "px-8 py-4 text-lg" },
|
|
863
|
-
},
|
|
864
|
-
states: {
|
|
865
|
-
hover: { className: "shadow-xl transform scale-105" },
|
|
866
|
-
},
|
|
867
|
-
},
|
|
868
|
-
},
|
|
869
|
-
};
|
|
870
|
-
```
|
|
871
|
-
|
|
872
|
-
### Advanced Announcement Styling
|
|
873
|
-
|
|
874
|
-
```typescript
|
|
875
|
-
const announcementStyling = {
|
|
876
|
-
theme: "brand",
|
|
877
|
-
tokens: {
|
|
878
|
-
colors: {
|
|
879
|
-
background: "linear-gradient(90deg, #667eea 0%, #764ba2 100%)",
|
|
880
|
-
text: "#ffffff",
|
|
881
|
-
},
|
|
882
|
-
transitions: {
|
|
883
|
-
smooth: "all 0.3s cubic-bezier(0.4, 0, 0.2, 1)",
|
|
884
|
-
},
|
|
885
|
-
},
|
|
886
|
-
slots: {
|
|
887
|
-
root: {
|
|
888
|
-
style: {
|
|
889
|
-
background: "var(--colors-background)",
|
|
890
|
-
transition: "var(--transitions-smooth)",
|
|
891
|
-
},
|
|
892
|
-
},
|
|
893
|
-
announcementText: {
|
|
894
|
-
className: "font-semibold tracking-wide",
|
|
895
|
-
states: {
|
|
896
|
-
hover: { className: "text-yellow-200" },
|
|
897
|
-
},
|
|
898
|
-
},
|
|
899
|
-
closeButton: {
|
|
900
|
-
className: "opacity-70 hover:opacity-100 transition-opacity",
|
|
901
|
-
},
|
|
902
|
-
},
|
|
903
|
-
};
|
|
904
|
-
```
|
|
905
|
-
|
|
906
|
-
---
|
|
907
|
-
|
|
908
437
|
## 🔑 API Key Setup
|
|
909
438
|
|
|
910
439
|
Before using the SDK, you need to generate an API key from your Fragment-Shopify app:
|
|
@@ -960,7 +489,7 @@ graph TD
|
|
|
960
489
|
2. **Publishing**: Sections are published and available via API
|
|
961
490
|
3. **Data Fetching**: Your app calls `fetchResource()` to get section data
|
|
962
491
|
4. **Component Rendering**: Pass data to Hero/Announcement components
|
|
963
|
-
5. **Styling Application**: Advanced styling system applies
|
|
492
|
+
5. **Styling Application**: Advanced styling system applies design tokens, responsive design, and interactions
|
|
964
493
|
6. **UI Display**: Components render beautiful, responsive, styled sections
|
|
965
494
|
|
|
966
495
|
---
|
|
@@ -994,8 +523,8 @@ const sections = await fetchResource({...});
|
|
|
994
523
|
fragment-headless-sdk/
|
|
995
524
|
├── src/
|
|
996
525
|
│ ├── components/ # React components
|
|
997
|
-
│ │ ├── Announcement/ # Announcement
|
|
998
|
-
│ │ └── Hero/ # Hero
|
|
526
|
+
│ │ ├── Announcement/ # Announcement components
|
|
527
|
+
│ │ └── Hero/ # Hero components
|
|
999
528
|
│ ├── constants/ # Enums and constants
|
|
1000
529
|
│ ├── types/ # TypeScript interfaces
|
|
1001
530
|
│ │ └── styling.ts # Advanced styling types
|
|
@@ -1004,150 +533,16 @@ fragment-headless-sdk/
|
|
|
1004
533
|
└── dist/ # Compiled output
|
|
1005
534
|
```
|
|
1006
535
|
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
## 🔄 Migration Guide
|
|
1010
|
-
|
|
1011
|
-
### From v2.0 to v2.1
|
|
1012
|
-
|
|
1013
|
-
**No Breaking Changes** - v2.1 is fully backward compatible!
|
|
1014
|
-
|
|
1015
|
-
All existing Hero components continue to work exactly as before. The new Hero Resolvers system is completely opt-in.
|
|
1016
|
-
|
|
1017
|
-
#### New Features Available (Optional)
|
|
1018
|
-
|
|
1019
|
-
```typescript
|
|
1020
|
-
// v2.0 style (continues to work)
|
|
1021
|
-
const heroContent = {
|
|
1022
|
-
title: "My Hero",
|
|
1023
|
-
styling: {
|
|
1024
|
-
tokens: {
|
|
1025
|
-
colors: {
|
|
1026
|
-
title: "#ffffff",
|
|
1027
|
-
button: "#007bff",
|
|
1028
|
-
},
|
|
1029
|
-
},
|
|
1030
|
-
},
|
|
1031
|
-
};
|
|
1032
|
-
|
|
1033
|
-
// v2.1 enhanced style (new features)
|
|
1034
|
-
const heroContent = {
|
|
1035
|
-
title: "My Hero",
|
|
1036
|
-
styling: {
|
|
1037
|
-
tokens: {
|
|
1038
|
-
colors: {
|
|
1039
|
-
title: "#ffffff",
|
|
1040
|
-
button: "#007bff",
|
|
1041
|
-
},
|
|
1042
|
-
// NEW: Typography controls
|
|
1043
|
-
typography: {
|
|
1044
|
-
titleFont: "montserrat",
|
|
1045
|
-
titleFontSize: "text-6xl",
|
|
1046
|
-
titleLineHeight: "leading-tight",
|
|
1047
|
-
},
|
|
1048
|
-
// NEW: Layout controls
|
|
1049
|
-
layout: {
|
|
1050
|
-
position: "center",
|
|
1051
|
-
contentWidth: "max-w-4xl",
|
|
1052
|
-
height: "min-h-screen",
|
|
1053
|
-
},
|
|
1054
|
-
},
|
|
1055
|
-
},
|
|
1056
|
-
};
|
|
1057
|
-
```
|
|
1058
|
-
|
|
1059
|
-
### From v1.x to v2.0
|
|
1060
|
-
|
|
1061
|
-
**No Breaking Changes** - v2.0 is fully backward compatible!
|
|
1062
|
-
|
|
1063
|
-
#### Option 1: Keep Using v1.x Style (No Changes Required)
|
|
1064
|
-
|
|
1065
|
-
```typescript
|
|
1066
|
-
// This continues to work exactly as before
|
|
1067
|
-
const content = {
|
|
1068
|
-
title: "My Hero",
|
|
1069
|
-
bgColor: "#ffffff",
|
|
1070
|
-
textColor: "#333333",
|
|
1071
|
-
};
|
|
1072
|
-
```
|
|
1073
|
-
|
|
1074
|
-
#### Option 2: Gradual Migration
|
|
1075
|
-
|
|
1076
|
-
```typescript
|
|
1077
|
-
// Start using new styling alongside legacy
|
|
1078
|
-
const content = {
|
|
1079
|
-
title: "My Hero",
|
|
1080
|
-
styling: {
|
|
1081
|
-
legacyTokens: {
|
|
1082
|
-
bgColor: "#ffffff", // Keep existing tokens
|
|
1083
|
-
textColor: "#333333",
|
|
1084
|
-
},
|
|
1085
|
-
tokens: {
|
|
1086
|
-
colors: {
|
|
1087
|
-
button: "#007bff", // Add new structured tokens
|
|
1088
|
-
},
|
|
1089
|
-
},
|
|
1090
|
-
},
|
|
1091
|
-
};
|
|
1092
|
-
```
|
|
1093
|
-
|
|
1094
|
-
#### Option 3: Full v2.0 Adoption
|
|
1095
|
-
|
|
1096
|
-
```typescript
|
|
1097
|
-
// Embrace the full power of v2.0
|
|
1098
|
-
const content = {
|
|
1099
|
-
title: "My Hero",
|
|
1100
|
-
styling: {
|
|
1101
|
-
theme: "dark",
|
|
1102
|
-
variant: "gradient",
|
|
1103
|
-
tokens: {
|
|
1104
|
-
colors: {
|
|
1105
|
-
background: "#1a1a1a",
|
|
1106
|
-
text: "#ffffff",
|
|
1107
|
-
button: "#007bff",
|
|
1108
|
-
},
|
|
1109
|
-
},
|
|
1110
|
-
slots: {
|
|
1111
|
-
title: {
|
|
1112
|
-
className: "text-4xl font-bold",
|
|
1113
|
-
responsive: {
|
|
1114
|
-
md: { className: "text-6xl" },
|
|
1115
|
-
},
|
|
1116
|
-
},
|
|
1117
|
-
},
|
|
1118
|
-
},
|
|
1119
|
-
};
|
|
1120
|
-
```
|
|
1121
|
-
|
|
1122
|
-
---
|
|
536
|
+
## 📚 Documentation
|
|
1123
537
|
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
2. Create corresponding TypeScript interfaces
|
|
1130
|
-
3. Build React components for rendering
|
|
1131
|
-
4. Add styling slot interfaces for type safety
|
|
1132
|
-
5. Update this documentation
|
|
538
|
+
- [CHANGELOG.md](./docs/CHANGELOG.md) - Release history and version notes
|
|
539
|
+
- [STYLING.md](./docs/STYLING.md) - Advanced styling system documentation
|
|
540
|
+
- [HERO-RESOLVERS.md](./docs/HERO-RESOLVERS.md) - Hero component customization guide
|
|
541
|
+
- [MIGRATION.md](./docs/MIGRATION.md) - Version migration guides
|
|
542
|
+
- [PUBLISHING.md](./docs/PUBLISHING.md) - NPM publishing guide
|
|
1133
543
|
|
|
1134
544
|
---
|
|
1135
545
|
|
|
1136
546
|
## 📝 License
|
|
1137
547
|
|
|
1138
548
|
MIT License - See LICENSE file for details.
|
|
1139
|
-
|
|
1140
|
-
---
|
|
1141
|
-
|
|
1142
|
-
## 🎉 What's Next?
|
|
1143
|
-
|
|
1144
|
-
The v2.1 Hero Resolvers system and v2.0 styling foundation provide unlimited customization and scalability. Future enhancements may include:
|
|
1145
|
-
|
|
1146
|
-
- Visual styling editor integration
|
|
1147
|
-
- Animation and transition presets
|
|
1148
|
-
- Advanced layout system for all components
|
|
1149
|
-
- Component composition utilities
|
|
1150
|
-
- Design system generator
|
|
1151
|
-
- Enhanced Announcement component resolvers
|
|
1152
|
-
|
|
1153
|
-
**Ready to build beautiful, scalable headless experiences with advanced typography and layout controls!** 🚀
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
@import url("https://fonts.googleapis.com/css2?family=Geist:wght@100..900&family=Geist+Mono:wght@100..900&family=Roboto:wght@300;400;500;700&family=Open+Sans:wght@300;400;600;700&family=Lato:wght@300;400;700&family=Montserrat:wght@300;400;500;700&family=Inter:wght@300;400;500;700&family=Poppins:wght@300;400;600;700&family=Raleway:wght@300;400;500;700&family=Playfair+Display:wght@400;700&family=Merriweather:wght@300;400;700&family=Oswald:wght@300;400;500;700&display=swap");
|
|
2
|
-
|
|
3
|
-
/* Custom animations for fragment-headless-sdk */
|
|
4
|
-
@keyframes marquee {
|
|
5
|
-
0% {
|
|
6
|
-
transform: translateX(0%);
|
|
7
|
-
}
|
|
8
|
-
100% {
|
|
9
|
-
transform: translateX(-100%);
|
|
10
|
-
}
|
|
11
|
-
}
|
|
12
|
-
|
|
13
|
-
/* Utility classes for marquee animations */
|
|
14
|
-
.animate-marquee {
|
|
15
|
-
animation: marquee 25s linear infinite;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
/* Make hero/announcement prose links inherit the surrounding text color (v2.1+) */
|
|
19
|
-
.prose {
|
|
20
|
-
--tw-prose-links: currentColor;
|
|
21
|
-
--tw-prose-links-hover: currentColor;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
|
-
.prose :where(a):not(:where([class~="not-prose"] *)) {
|
|
25
|
-
color: currentColor;
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
.prose :where(a):not(:where([class~="not-prose"] *)):hover {
|
|
29
|
-
color: currentColor;
|
|
30
|
-
text-decoration: underline;
|
|
31
|
-
}
|