@tramo-digital/types 0.0.0

package/README.md

@@ -0,0 +1,220 @@
+# @tramo-digital/types
+
+TypeScript type definitions for the Open Design System component-driven design system. This library provides type-safe component models, validation utilities, and Standard Schema integration for building scalable, data-driven UI components.
+
+## Installation
+
+```bash
+npm install @tramo-digital/types
+# or
+pnpm add @tramo-digital/types
+# or
+pnpm add @tramo-digital/types
+```
+
+## Overview
+
+This library provides a modern, data-driven approach to component typing with:
+
+- **Component Models** - Data-centric component definitions with type safety
+- **Standard Schema Integration** - Runtime validation with library-agnostic schema support  
+- **Loader System** - Async data loading with validation for server-side rendering
+- **Utility Types** - String manipulation and type transformation helpers
+- **Framework Agnostic** - Works with React, Vue, and vanilla JavaScript
+
+## Core Concepts
+
+### Component Models
+
+Components are defined as data models with optional loaders, events, and validation:
+
+```typescript
+import { HeroModel, BaseComponentModel } from '@tramo-digital/types';
+
+// Pre-built component models
+const hero: HeroModel = {
+  _type: 'hero',
+  data: {
+    title: 'Welcome to our platform',
+    subtitle: 'Build amazing experiences',
+    ctaText: 'Get Started',
+    ctaLink: '/signup'
+  },
+  events: {
+    onCtaClick: (event) => console.log('CTA clicked', event)
+  }
+};
+
+// Create custom component models
+interface CustomModel extends BaseComponentModel<'custom', MyData, MyEvents> {}
+```
+
+### Standard Schema Integration
+
+Leverage any Standard Schema compatible library (Zod, Valibot, ArkType) for validation:
+
+```typescript
+import { z } from 'zod';
+import { BaseComponentModelWithSchema, safeValidateWithSchema } from '@tramo-digital/types';
+
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user'])
+});
+
+interface UserComponent extends BaseComponentModelWithSchema<
+  'user',
+  typeof UserSchema,
+  UserEvents
+> {}
+
+const userComponent: UserComponent = {
+  _type: 'user',
+  _schema: UserSchema,
+  loader: async (context) => {
+    const userData = await fetchUser(context?.user?.id);
+    return await safeValidateWithSchema(UserSchema, userData);
+  }
+};
+```
+
+### Async Data Loading
+
+Components can load and validate data asynchronously:
+
+```typescript
+import { ComponentLoader, LoaderContext } from '@tramo-digital/types';
+
+const createHeroLoader: ComponentLoader<HeroData> = async (context) => {
+  try {
+    const data = await fetchHeroFromCMS(context?.request?.params?.id);
+    return { value: data }; // Success result
+  } catch (error) {
+    return { issues: [{ message: 'Failed to load hero data' }] }; // Error result
+  }
+};
+```
+
+## 📦 Available Components
+
+### Primitive Components
+- `ButtonModel` - Interactive button components
+- `IconModel` - Icon display components  
+- `ImageModel` - Image components with responsive features
+- `ContentModel` - Text content components
+- `AccordionItemModel` - Individual accordion panels
+- `CarouselItemModel` - Carousel slide components
+
+### Pattern Components  
+- `HeroModel` - Hero sections with CTA
+- `CardModel` - Content cards
+- `AccordionModel` - Expandable content sections
+- `CarouselModel` - Image/content sliders
+- `BannerModel` - Promotional banners
+- `MarqueeModel` - Scrolling text displays
+- `CountdownTimerModel` - Timer components
+
+### Layout Components
+- `GridContainerModel` - CSS Grid containers
+- `GridItemModel` - Grid item positioning
+- `OneColModel` - Single column layouts
+- `TwoColModel` - Two column layouts
+
+### Composition Components
+- `HeroAccordionModel` - Hero sections with integrated accordions
+
+## 🛠 Utility Types
+
+Transform and manipulate types with built-in utilities:
+
+```typescript
+import { ToSnakeCase, ToPascalCase, ComponentType } from '@tramo-digital/types';
+
+type Example1 = ToSnakeCase<'MyComponent'>; // 'my_component'
+type Example2 = ToPascalCase<'my_component'>; // 'MyComponent'
+type Example3 = ComponentType<'UserCard'>; // 'user_card'
+
+// Filter components by type
+type HeroComponents = FilterByType<AllComponents, 'hero'>;
+
+// Make specific properties optional/required
+type PartialHero = PartialBy<HeroModel, 'events' | 'loader'>;
+type RequiredHero = RequiredBy<HeroModel, 'data'>;
+```
+
+## 🔒 Runtime Validation
+
+Validate data at runtime with Standard Schema compatible validators:
+
+```typescript
+import { 
+  validateWithSchema, 
+  safeValidateWithSchema,
+  isStandardSchema,
+  ValidationError 
+} from '@tramo-digital/types';
+
+// Throws on validation failure  
+const validData = await validateWithSchema(schema, data);
+
+// Returns result object (safe, no throwing)
+const result = await safeValidateWithSchema(schema, data);
+if ('issues' in result) {
+  console.error('Validation failed:', result.issues);
+} else {
+  console.log('Valid data:', result.value);
+}
+
+// Check if object is a valid schema
+if (isStandardSchema(someSchema)) {
+  // Safe to use with validation functions
+}
+```
+
+## 🔧 Framework Integration
+
+Works seamlessly with popular frameworks:
+
+```typescript
+// React
+import { HeroModel } from '@tramo-digital/types';
+const HeroComponent: React.FC<{ model: HeroModel }> = ({ model }) => {
+  // Use model.data, model.events, etc.
+};
+
+// Vue
+import { HeroModel } from '@tramo-digital/types';
+defineComponent({
+  props: {
+    model: { type: Object as PropType<HeroModel>, required: true }
+  }
+});
+
+```
+
+## 🎯 Best Practices
+
+1. **Use Type-Safe Models**: Always use the provided component models for consistency
+2. **Validate External Data**: Use schema validation for data from APIs or user input  
+3. **Leverage Loaders**: Use component loaders for async data fetching with error handling
+4. **Compose Components**: Build complex UIs by composing simpler component models
+5. **Framework Agnostic**: Keep business logic in models, UI logic in framework components
+
+## 📚 Advanced Usage
+
+For detailed examples and advanced patterns, see:
+- [Standard Schema Integration Guide](./STANDARD_SCHEMA_INTEGRATION.md)
+- Component-specific documentation in `/src/models/`
+
+## 🤝 Contributing
+
+This library uses:
+- **TypeScript 5.8+** for modern type features
+- **Standard Schema v1** for validation interfaces  
+- **ESM modules** for modern bundle compatibility
+- **Strict type checking** for maximum safety
+
+## 📄 License
+
+Part of the Open Design System design system. See main repository for license details.

package/dist/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @tramo-digital/types
+
+## 0.0.9
+
+### Patch Changes
+
+- Add loader property to base model
+
+## 0.0.8
+
+### Patch Changes
+
+- Auto-generated changeset by GitHub Action
+
+## 0.0.6
+
+### Patch Changes
+
+- b0789d8: Add tokens override example in Text Block
+
+## 0.0.5
+
+### Patch Changes
+
+- Add base design tokens types
+
+## 0.0.4
+
+### Patch Changes
+
+- 2a3f941: Removed React reference from library

package/dist/README.md

@@ -0,0 +1,220 @@
+# @tramo-digital/types
+
+TypeScript type definitions for the Open Design System component-driven design system. This library provides type-safe component models, validation utilities, and Standard Schema integration for building scalable, data-driven UI components.
+
+## Installation
+
+```bash
+npm install @tramo-digital/types
+# or
+pnpm add @tramo-digital/types
+# or
+pnpm add @tramo-digital/types
+```
+
+## Overview
+
+This library provides a modern, data-driven approach to component typing with:
+
+- **Component Models** - Data-centric component definitions with type safety
+- **Standard Schema Integration** - Runtime validation with library-agnostic schema support  
+- **Loader System** - Async data loading with validation for server-side rendering
+- **Utility Types** - String manipulation and type transformation helpers
+- **Framework Agnostic** - Works with React, Vue, and vanilla JavaScript
+
+## Core Concepts
+
+### Component Models
+
+Components are defined as data models with optional loaders, events, and validation:
+
+```typescript
+import { HeroModel, BaseComponentModel } from '@tramo-digital/types';
+
+// Pre-built component models
+const hero: HeroModel = {
+  _type: 'hero',
+  data: {
+    title: 'Welcome to our platform',
+    subtitle: 'Build amazing experiences',
+    ctaText: 'Get Started',
+    ctaLink: '/signup'
+  },
+  events: {
+    onCtaClick: (event) => console.log('CTA clicked', event)
+  }
+};
+
+// Create custom component models
+interface CustomModel extends BaseComponentModel<'custom', MyData, MyEvents> {}
+```
+
+### Standard Schema Integration
+
+Leverage any Standard Schema compatible library (Zod, Valibot, ArkType) for validation:
+
+```typescript
+import { z } from 'zod';
+import { BaseComponentModelWithSchema, safeValidateWithSchema } from '@tramo-digital/types';
+
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user'])
+});
+
+interface UserComponent extends BaseComponentModelWithSchema<
+  'user',
+  typeof UserSchema,
+  UserEvents
+> {}
+
+const userComponent: UserComponent = {
+  _type: 'user',
+  _schema: UserSchema,
+  loader: async (context) => {
+    const userData = await fetchUser(context?.user?.id);
+    return await safeValidateWithSchema(UserSchema, userData);
+  }
+};
+```
+
+### Async Data Loading
+
+Components can load and validate data asynchronously:
+
+```typescript
+import { ComponentLoader, LoaderContext } from '@tramo-digital/types';
+
+const createHeroLoader: ComponentLoader<HeroData> = async (context) => {
+  try {
+    const data = await fetchHeroFromCMS(context?.request?.params?.id);
+    return { value: data }; // Success result
+  } catch (error) {
+    return { issues: [{ message: 'Failed to load hero data' }] }; // Error result
+  }
+};
+```
+
+## 📦 Available Components
+
+### Primitive Components
+- `ButtonModel` - Interactive button components
+- `IconModel` - Icon display components  
+- `ImageModel` - Image components with responsive features
+- `ContentModel` - Text content components
+- `AccordionItemModel` - Individual accordion panels
+- `CarouselItemModel` - Carousel slide components
+
+### Pattern Components  
+- `HeroModel` - Hero sections with CTA
+- `CardModel` - Content cards
+- `AccordionModel` - Expandable content sections
+- `CarouselModel` - Image/content sliders
+- `BannerModel` - Promotional banners
+- `MarqueeModel` - Scrolling text displays
+- `CountdownTimerModel` - Timer components
+
+### Layout Components
+- `GridContainerModel` - CSS Grid containers
+- `GridItemModel` - Grid item positioning
+- `OneColModel` - Single column layouts
+- `TwoColModel` - Two column layouts
+
+### Composition Components
+- `HeroAccordionModel` - Hero sections with integrated accordions
+
+## 🛠 Utility Types
+
+Transform and manipulate types with built-in utilities:
+
+```typescript
+import { ToSnakeCase, ToPascalCase, ComponentType } from '@tramo-digital/types';
+
+type Example1 = ToSnakeCase<'MyComponent'>; // 'my_component'
+type Example2 = ToPascalCase<'my_component'>; // 'MyComponent'
+type Example3 = ComponentType<'UserCard'>; // 'user_card'
+
+// Filter components by type
+type HeroComponents = FilterByType<AllComponents, 'hero'>;
+
+// Make specific properties optional/required
+type PartialHero = PartialBy<HeroModel, 'events' | 'loader'>;
+type RequiredHero = RequiredBy<HeroModel, 'data'>;
+```
+
+## 🔒 Runtime Validation
+
+Validate data at runtime with Standard Schema compatible validators:
+
+```typescript
+import { 
+  validateWithSchema, 
+  safeValidateWithSchema,
+  isStandardSchema,
+  ValidationError 
+} from '@tramo-digital/types';
+
+// Throws on validation failure  
+const validData = await validateWithSchema(schema, data);
+
+// Returns result object (safe, no throwing)
+const result = await safeValidateWithSchema(schema, data);
+if ('issues' in result) {
+  console.error('Validation failed:', result.issues);
+} else {
+  console.log('Valid data:', result.value);
+}
+
+// Check if object is a valid schema
+if (isStandardSchema(someSchema)) {
+  // Safe to use with validation functions
+}
+```
+
+## 🔧 Framework Integration
+
+Works seamlessly with popular frameworks:
+
+```typescript
+// React
+import { HeroModel } from '@tramo-digital/types';
+const HeroComponent: React.FC<{ model: HeroModel }> = ({ model }) => {
+  // Use model.data, model.events, etc.
+};
+
+// Vue
+import { HeroModel } from '@tramo-digital/types';
+defineComponent({
+  props: {
+    model: { type: Object as PropType<HeroModel>, required: true }
+  }
+});
+
+```
+
+## 🎯 Best Practices
+
+1. **Use Type-Safe Models**: Always use the provided component models for consistency
+2. **Validate External Data**: Use schema validation for data from APIs or user input  
+3. **Leverage Loaders**: Use component loaders for async data fetching with error handling
+4. **Compose Components**: Build complex UIs by composing simpler component models
+5. **Framework Agnostic**: Keep business logic in models, UI logic in framework components
+
+## 📚 Advanced Usage
+
+For detailed examples and advanced patterns, see:
+- [Standard Schema Integration Guide](./STANDARD_SCHEMA_INTEGRATION.md)
+- Component-specific documentation in `/src/models/`
+
+## 🤝 Contributing
+
+This library uses:
+- **TypeScript 5.8+** for modern type features
+- **Standard Schema v1** for validation interfaces  
+- **ESM modules** for modern bundle compatibility
+- **Strict type checking** for maximum safety
+
+## 📄 License
+
+Part of the Open Design System design system. See main repository for license details.

package/dist/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tramo-digital/types",
+  "version": "0.0.0",
+  "description": "tramo.digital - types",
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "author": "carlosp0veda",
+  "license": "MIT",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.d.ts",
+      "require": "./dist/src/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc -b .",
+    "publish": "pnpm publish",
+    "publish-local": "npm publish --registry http://localhost:4873 --access public"
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "volta": {
+    "node": "22.16.0",
+    "pnpm": "10.4.0"
+  },
+  "module": "./src/index.js",
+  "main": "./src/index.js"
+}

package/dist/src/base/component.d.ts

@@ -0,0 +1,75 @@
+import type { StandardSchemaV1 } from '../schema/index.js';
+import type { ComponentLoaderWithSchema, SimpleLoader } from './data-loader.js';
+import type { BaseDesignTokens, ColorPalette, ColorSource, CustomColor } from './design-tokens.js';
+/**
+ * Base Component Model Interface
+ *
+ * Core interface that all component models must extend.
+ * Provides the foundational structure for component data models.
+ */
+export type BaseComponentModel<ComponentType = string, TData = Record<string, unknown>, TEvents = Record<string, unknown>, TTokens extends BaseDesignTokens = BaseDesignTokens> = {
+    /** Optional unique identifier for the component */
+    id?: string;
+    /** Generic data object that holds all dynamic content data for the component */
+    data?: TData;
+    /** Optional event handlers */
+    events?: TEvents;
+    /** Design token overrides */
+    tokens?: TTokens;
+    /** Optional classname for additional styling */
+    className?: string;
+    /** Optional color palette for the component */
+    colorPalette?: ColorPalette;
+    /** Optional custom color for the component */
+    customColor?: CustomColor;
+    /** Optional color source for the component */
+    colorSource?: ColorSource;
+    /** Optional loader that can be used to load the data for the component */
+    loader?: SimpleLoader<TData>;
+    /**
+     * Unique component type identifier in snake_case
+     * Should match the component name converted to snake_case
+     * Examples: 'button', 'hero', 'grid_container', 'accordion_item'
+     */
+    _type?: ComponentType;
+};
+/**
+ * Enhanced Base Component Model with Schema Validation
+ *
+ * Supports Standard Schema compatible validators from external libraries
+ * like Zod, Valibot, ArkType, etc.
+ */
+export interface BaseComponentModelWithSchema<ComponentType = string, Schema extends StandardSchemaV1 = StandardSchemaV1, TEvents = Record<string, unknown>, TTokens extends BaseDesignTokens = BaseDesignTokens> {
+    id?: string;
+    /** Optional event handlers */
+    events?: TEvents;
+    /** Design token overrides */
+    tokens?: TTokens;
+    /** Generic data object that holds all dynamic content data for the component */
+    data?: StandardSchemaV1.InferOutput<Schema>;
+    /** Optional color source for the component */
+    colorSource?: ColorSource;
+    /** Optional custom color for the component */
+    customColor?: CustomColor;
+    /** Optional color palette for the component */
+    colorPalette?: ColorPalette;
+    /**
+     * Standard Schema compatible validator for component data
+     * Can be from Zod, Valibot, ArkType, or any other compatible library
+     */
+    _schema?: Schema;
+    /**
+     * Enhanced loader that works with the schema validator
+     * Returns validated component data using Standard Schema result pattern
+     */
+    loader?: ComponentLoaderWithSchema<Schema>;
+    /**
+     * Unique component type identifier in snake_case
+     * Should match the component name converted to snake_case
+     * Examples: 'button', 'hero', 'grid_container', 'accordion_item'
+     */
+    _type: ComponentType;
+}
+/** Backward compatibility alias */
+export type ComponentModel<ComponentType = string, Data = Record<string, unknown>, Events = Record<string, unknown>, TTokens extends BaseDesignTokens = BaseDesignTokens> = BaseComponentModel<ComponentType, Data, Events, TTokens>;
+//# sourceMappingURL=component.d.ts.map

package/dist/src/base/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/base/component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAC5B,aAAa,GAAG,MAAM,EACtB,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB,IACjD;IACF,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B,CAC3C,aAAa,GAAG,MAAM,EACtB,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IAEnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,IAAI,CAAC,EAAE,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+CAA+C;IAC/C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAC3C;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,mCAAmC;AACnC,MAAM,MAAM,cAAc,CACxB,aAAa,GAAG,MAAM,EACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB,IACjD,kBAAkB,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/src/base/component.js

@@ -0,0 +1 @@
+export {};