@hua-labs/hua-ux 0.1.0-alpha.0.1

package/dist/framework/seo/geo/test-utils.js

@@ -0,0 +1,139 @@
+/**
+ * @hua-labs/hua-ux/framework - GEO Test Utilities
+ *
+ * Testing utilities for GEO metadata validation and debugging
+ * GEO 메타데이터 검증 및 디버깅을 위한 테스트 유틸리티
+ */
+/**
+ * Validate GEO metadata
+ *
+ * GEO 메타데이터의 유효성을 검증합니다.
+ *
+ * @param metadata - GEO metadata to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```tsx
+ * const result = validateGEOMetadata(geoMeta);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export function validateGEOMetadata(metadata) {
+    const errors = [];
+    const warnings = [];
+    // Validate meta tags
+    const descMeta = metadata.meta.find(m => m.name === 'description');
+    if (!descMeta) {
+        errors.push('Missing description meta tag');
+    }
+    else if (descMeta.content.length === 0) {
+        errors.push('Description meta tag is empty');
+    }
+    else if (descMeta.content.length > 160) {
+        warnings.push(`Description exceeds 160 characters (${descMeta.content.length}). ` +
+            'Consider keeping it under 160 for better AI parsing.');
+    }
+    // Validate JSON-LD
+    if (!metadata.jsonLd || metadata.jsonLd.length === 0) {
+        errors.push('Missing JSON-LD structured data');
+    }
+    else {
+        for (const ld of metadata.jsonLd) {
+            if (!ld['@context'] || ld['@context'] !== 'https://schema.org') {
+                errors.push('Invalid JSON-LD structure: missing or invalid @context');
+            }
+            if (!ld['@type']) {
+                errors.push('Invalid JSON-LD structure: missing @type');
+            }
+        }
+    }
+    // Validate URLs in meta tags
+    metadata.meta.forEach(meta => {
+        if (meta.content.startsWith('http')) {
+            try {
+                new URL(meta.content);
+            }
+            catch {
+                errors.push(`Invalid URL in meta tag ${meta.name}: ${meta.content}`);
+            }
+        }
+    });
+    // Validate Open Graph tags
+    if (metadata.openGraph) {
+        const requiredOG = ['og:title', 'og:description', 'og:type'];
+        const ogProperties = metadata.openGraph.map(og => og.property);
+        for (const required of requiredOG) {
+            if (!ogProperties.includes(required)) {
+                warnings.push(`Missing recommended Open Graph property: ${required}`);
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Pretty print GEO metadata
+ *
+ * GEO 메타데이터를 읽기 쉬운 형식으로 출력합니다.
+ *
+ * @param metadata - GEO metadata to print
+ * @returns Formatted JSON string
+ *
+ * @example
+ * ```tsx
+ * console.log(prettyPrintGEOMetadata(geoMeta));
+ * ```
+ */
+export function prettyPrintGEOMetadata(metadata) {
+    return JSON.stringify(metadata, null, 2);
+}
+/**
+ * Compare two GEO metadata objects
+ *
+ * 두 GEO 메타데이터 객체를 비교합니다.
+ *
+ * @param a - First GEO metadata
+ * @param b - Second GEO metadata
+ * @returns Comparison result with differences
+ *
+ * @example
+ * ```tsx
+ * const result = compareGEOMetadata(meta1, meta2);
+ * if (!result.same) {
+ *   console.log('Differences:', result.differences);
+ * }
+ * ```
+ */
+export function compareGEOMetadata(a, b) {
+    const differences = [];
+    // Compare meta tags
+    const aMetaMap = new Map(a.meta.map(m => [m.name, m.content]));
+    const bMetaMap = new Map(b.meta.map(m => [m.name, m.content]));
+    for (const [name, content] of aMetaMap) {
+        if (bMetaMap.get(name) !== content) {
+            differences.push(`Meta tag '${name}' differs`);
+        }
+    }
+    for (const [name] of bMetaMap) {
+        if (!aMetaMap.has(name)) {
+            differences.push(`Meta tag '${name}' missing in first metadata`);
+        }
+    }
+    // Compare JSON-LD count
+    if (a.jsonLd.length !== b.jsonLd.length) {
+        differences.push(`JSON-LD count differs: ${a.jsonLd.length} vs ${b.jsonLd.length}`);
+    }
+    // Compare version
+    if (a.version !== b.version) {
+        differences.push(`Version differs: ${a.version} vs ${b.version}`);
+    }
+    return {
+        same: differences.length === 0,
+        differences,
+    };
+}

package/dist/framework/seo/geo/types.d.ts

@@ -0,0 +1,225 @@
+/**
+ * @hua-labs/hua-ux/framework - GEO Types
+ *
+ * GEO (Generative Engine Optimization) types for AI search engine discoverability
+ * ChatGPT, Claude, Gemini, Perplexity 같은 AI가 hua-ux를 잘 찾고 추천하도록 하는 타입 정의
+ */
+/**
+ * Meta tag name constants
+ * HTML meta 태그 이름 상수
+ */
+export declare const META_NAMES: {
+    readonly DESCRIPTION: "description";
+    readonly KEYWORDS: "keywords";
+    readonly SOFTWARE_VERSION: "software:version";
+    readonly SOFTWARE_CATEGORY: "software:category";
+    readonly SOFTWARE_LANGUAGE: "software:language";
+    readonly AI_CONTEXT: "ai:context";
+};
+/**
+ * Open Graph property constants
+ * Open Graph 속성 상수
+ */
+export declare const OG_PROPERTIES: {
+    readonly TITLE: "og:title";
+    readonly DESCRIPTION: "og:description";
+    readonly TYPE: "og:type";
+    readonly URL: "og:url";
+    readonly SITE_NAME: "og:site_name";
+};
+/**
+ * Software Application Type
+ * Schema.org SoftwareApplication types
+ */
+export type SoftwareApplicationType = 'WebApplication' | 'MobileApplication' | 'DesktopApplication' | 'DeveloperApplication';
+/**
+ * Programming Language
+ * 프로그래밍 언어 (프레임워크가 아닌 실제 언어만)
+ */
+export type ProgrammingLanguage = 'TypeScript' | 'JavaScript' | 'Python' | 'Java' | 'Go' | 'Rust' | 'C#' | 'C++' | 'Ruby' | 'PHP' | 'Swift' | 'Kotlin' | 'Dart' | (string & {});
+/**
+ * Technology Stack
+ * 기술 스택 (프레임워크, 라이브러리 등)
+ */
+export type TechnologyStack = 'React' | 'Next.js' | 'Vue' | 'Angular' | 'Svelte' | 'Node.js' | 'Express' | 'Tailwind CSS' | 'Zustand' | 'Prisma' | (string & {});
+/**
+ * Software Category
+ * Categories that help AI understand the software domain
+ */
+export type SoftwareCategory = 'UI Framework' | 'Component Library' | 'Developer Tool' | 'UX Framework' | 'Accessibility Tool' | 'Internationalization Tool' | 'Animation Library';
+/**
+ * GEO Configuration
+ * AI 검색 엔진이 이해하기 쉬운 구조화된 메타데이터 설정
+ */
+export interface GEOConfig {
+    /**
+     * Software name
+     * AI가 참조할 소프트웨어 이름
+     */
+    name: string;
+    /**
+     * Alternative names or aliases
+     * 대체 이름 또는 별칭 (예: "hua-ux", "@hua-labs/hua-ux")
+     */
+    alternateName?: string[];
+    /**
+     * Clear, concise description
+     * AI가 이해하기 쉬운 명확하고 간결한 설명 (1-2 문장)
+     */
+    description: string;
+    /**
+     * Software version
+     */
+    version?: string;
+    /**
+     * Application category
+     * Schema.org applicationCategory
+     */
+    applicationCategory?: SoftwareCategory | SoftwareCategory[];
+    /**
+     * Programming language(s)
+     * 프로그래밍 언어 (TypeScript, JavaScript, Python 등)
+     */
+    programmingLanguage?: ProgrammingLanguage | ProgrammingLanguage[];
+    /**
+     * Technology stack
+     * 기술 스택 (React, Next.js, Vue 등)
+     */
+    technologyStack?: TechnologyStack | TechnologyStack[];
+    /**
+     * Software type
+     */
+    applicationType?: SoftwareApplicationType;
+    /**
+     * Homepage URL
+     */
+    url?: string;
+    /**
+     * Documentation URL
+     */
+    documentationUrl?: string;
+    /**
+     * Repository URL (GitHub, GitLab, etc.)
+     */
+    codeRepository?: string;
+    /**
+     * License type (MIT, Apache-2.0, etc.)
+     */
+    license?: string;
+    /**
+     * Author or organization
+     */
+    author?: {
+        name: string;
+        url?: string;
+    };
+    /**
+     * Key features
+     * AI가 쉽게 참조할 수 있는 주요 기능 목록
+     */
+    features?: string[];
+    /**
+     * Use cases
+     * AI가 추천할 때 사용할 유스케이스 예시
+     */
+    useCases?: string[];
+    /**
+     * Keywords for AI discovery
+     * AI 검색을 위한 키워드
+     */
+    keywords?: string[];
+    /**
+     * Operating system compatibility
+     */
+    operatingSystem?: string[];
+    /**
+     * Software requirements or dependencies
+     */
+    softwareRequirements?: string[];
+    /**
+     * Related software or alternatives
+     * AI가 비교/추천할 때 사용할 관련 소프트웨어
+     */
+    relatedTo?: string[];
+}
+/**
+ * Utility types for better developer experience
+ * 더 나은 개발자 경험을 위한 유틸리티 타입
+ */
+/**
+ * Required GEO config fields
+ * 필수 GEO 설정 필드
+ */
+export type RequiredGEOConfig = Required<Pick<GEOConfig, 'name' | 'description'>>;
+/**
+ * Optional GEO config fields
+ * 선택적 GEO 설정 필드
+ */
+export type OptionalGEOConfig = Partial<Omit<GEOConfig, 'name' | 'description'>>;
+/**
+ * GEO config input type
+ * GEO 설정 입력 타입 (필수 + 선택)
+ */
+export type GEOConfigInput = RequiredGEOConfig & OptionalGEOConfig;
+/**
+ * Type guard for GEO config validation
+ * GEO 설정 유효성 검사를 위한 타입 가드
+ *
+ * @param config - Unknown value to check
+ * @returns True if config is a valid GEOConfig
+ *
+ * @example
+ * ```tsx
+ * if (isValidGEOConfig(userInput)) {
+ *   const geoMeta = generateGEOMetadata(userInput);
+ * }
+ * ```
+ */
+export declare function isValidGEOConfig(config: unknown): config is GEOConfig;
+/**
+ * Structured Data (Schema.org JSON-LD)
+ * AI가 파싱하기 쉬운 구조화된 데이터
+ */
+export interface StructuredData {
+    '@context': 'https://schema.org';
+    '@type': 'SoftwareApplication' | 'FAQPage' | 'TechArticle' | 'HowTo' | 'Question' | 'Answer' | 'Organization' | 'CreativeWork' | 'Code' | 'VideoObject';
+    [key: string]: string | number | boolean | object | unknown[] | undefined;
+}
+/**
+ * GEO Metadata Result
+ * generateGEOMetadata() 함수의 반환 타입
+ */
+export interface GEOMetadata {
+    /**
+     * HTML meta tags
+     */
+    meta: {
+        name: string;
+        content: string;
+    }[];
+    /**
+     * JSON-LD structured data
+     * Schema.org 구조화된 데이터
+     */
+    jsonLd: StructuredData[];
+    /**
+     * Open Graph tags for social/AI sharing
+     */
+    openGraph?: {
+        property: string;
+        content: string;
+    }[];
+    /**
+     * Twitter Card tags
+     */
+    twitter?: {
+        name: string;
+        content: string;
+    }[];
+    /**
+     * Schema version
+     * GEO 메타데이터 스키마 버전 (향후 마이그레이션 및 디버깅용)
+     */
+    version?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/framework/seo/geo/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/framework/seo/geo/types.ts"],"names":[],"mappings":"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"}

package/dist/framework/seo/geo/types.js

@@ -0,0 +1,51 @@
+/**
+ * @hua-labs/hua-ux/framework - GEO Types
+ *
+ * GEO (Generative Engine Optimization) types for AI search engine discoverability
+ * ChatGPT, Claude, Gemini, Perplexity 같은 AI가 hua-ux를 잘 찾고 추천하도록 하는 타입 정의
+ */
+/**
+ * Meta tag name constants
+ * HTML meta 태그 이름 상수
+ */
+export const META_NAMES = {
+    DESCRIPTION: 'description',
+    KEYWORDS: 'keywords',
+    SOFTWARE_VERSION: 'software:version',
+    SOFTWARE_CATEGORY: 'software:category',
+    SOFTWARE_LANGUAGE: 'software:language',
+    AI_CONTEXT: 'ai:context',
+};
+/**
+ * Open Graph property constants
+ * Open Graph 속성 상수
+ */
+export const OG_PROPERTIES = {
+    TITLE: 'og:title',
+    DESCRIPTION: 'og:description',
+    TYPE: 'og:type',
+    URL: 'og:url',
+    SITE_NAME: 'og:site_name',
+};
+/**
+ * Type guard for GEO config validation
+ * GEO 설정 유효성 검사를 위한 타입 가드
+ *
+ * @param config - Unknown value to check
+ * @returns True if config is a valid GEOConfig
+ *
+ * @example
+ * ```tsx
+ * if (isValidGEOConfig(userInput)) {
+ *   const geoMeta = generateGEOMetadata(userInput);
+ * }
+ * ```
+ */
+export function isValidGEOConfig(config) {
+    return (typeof config === 'object' &&
+        config !== null &&
+        'name' in config &&
+        'description' in config &&
+        typeof config.name === 'string' &&
+        typeof config.description === 'string');
+}