@urbicon-ui/shared-types 6.1.4

package/src/documentation.ts

@@ -0,0 +1,49 @@
+/**
+ * Component metadata (shared across all packages)
+ */
+export interface ComponentMetadata {
+  version?: string;
+  description: string;
+  tags: string[];
+  deprecated?: DeprecationInfo;
+  experimental?: boolean;
+  since?: string;
+}
+
+export interface DeprecationInfo {
+  message: string;
+  since: string;
+  alternative?: string;
+  removeIn?: string;
+}
+
+/**
+ * Badge configuration (used in multiple packages)
+ */
+export interface ComponentBadge {
+  label: string;
+  intent?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info';
+  variant?: 'filled' | 'outlined' | 'soft';
+}
+
+/**
+ * Section ordering concept
+ */
+export interface SectionOrder {
+  id: string;
+  order: number;
+}
+
+/**
+ * Basic LLM configuration (shared between docs generators)
+ */
+export interface LLMConfig {
+  include?: boolean;
+  maxSections?: number;
+  priority?: string[];
+  excludeTypes?: string[];
+  simplifyContent?: boolean;
+}
+
+// Re-export for backward compatibility
+export type { DeprecationInfo as ComponentDeprecationInfo };

package/src/examples.ts

@@ -0,0 +1,73 @@
+/**
+ * Component example definition
+ */
+export interface ComponentExample {
+  /** Unique example identifier */
+  id: string;
+  /** Example title */
+  title: string;
+  /** Example description */
+  description?: string;
+  /** Example source code */
+  code: string;
+  /** Associated component name */
+  component?: string;
+  /** Include in LLM output */
+  includeLLM?: boolean;
+  /** Include in documentation */
+  includeDocs?: boolean;
+  /** Associated tags */
+  tags?: string[];
+}
+
+/**
+ * Usage pattern definition
+ */
+export interface UsagePattern {
+  /** Unique pattern identifier */
+  id: string;
+  /** Pattern title */
+  title: string;
+  /** Pattern description */
+  description: string;
+  /** When to use this pattern */
+  when: string;
+  /** When to avoid this pattern */
+  avoid: string;
+  /** Example implementations */
+  examples: string[];
+  /** Related components */
+  relatedComponents?: string[];
+  /** Include in LLM output */
+  includeLLM?: boolean;
+}
+
+/**
+ * Example collection with grouping
+ */
+export interface ExampleCollection {
+  /** Collection identifier */
+  id: string;
+  /** Collection title */
+  title: string;
+  /** Collection description */
+  description?: string;
+  /** Grouped examples */
+  groups: ExampleGroup[];
+}
+
+/**
+ * Example group within a collection
+ */
+export interface ExampleGroup {
+  /** Group identifier */
+  id: string;
+  /** Group title */
+  title: string;
+  /** Group description */
+  description?: string;
+  /** Examples in this group */
+  examples: ComponentExample[];
+  /** Group order */
+  order?: number;
+}

package/src/globals.ts

@@ -0,0 +1,17 @@
+/**
+ * Global type augmentations used across all packages
+ * Extends standard HTML attributes with custom properties
+ */
+
+declare global {
+  // Svelte's type system requires the `svelteHTML` namespace for template-
+  // attribute augmentation; module syntax is not a valid alternative here.
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace svelteHTML {
+    interface HTMLAttributes<T> {
+      onoutclick?: (event: CustomEvent) => void;
+    }
+  }
+}
+
+export {}; // Make this a module

package/src/index.ts

@@ -0,0 +1,87 @@
+// Core documentation types (original)
+
+// Core component types
+export type {
+  ComponentInfo,
+  ComponentStats,
+  CrossReference,
+  InheritanceInfo,
+  PackageInfo,
+  PropExample,
+  PropInfo,
+  PropSource,
+  VariantExample,
+  VariantInfo
+} from './component.js';
+
+// Svelte docs configuration types (original)
+export type {
+  ApiConfig,
+  DocsMetadata,
+  DocsPlaygroundConfig,
+  ExamplesConfig,
+  OverviewConfig,
+  SvelteDocsConfig,
+  UsageConfig,
+  VariantsConfig
+} from './docs-config.js';
+export type {
+  ComponentBadge,
+  ComponentMetadata,
+  DeprecationInfo,
+  LLMConfig,
+  SectionOrder
+} from './documentation.js';
+
+// (documentation-core types not re-exported anymore)
+
+// Example and pattern types
+export type {
+  ComponentExample,
+  ExampleCollection,
+  ExampleGroup,
+  UsagePattern
+} from './examples.js';
+// Navigation types
+export type {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbSettings,
+  NavigationBadge,
+  NavigationContext,
+  NavigationItem,
+  NavigationMetadata,
+  NavigationSearchResult,
+  NavigationState,
+  SearchMatch,
+  SiteNavigation,
+  TableOfContents,
+  TOCItem,
+  TOCSettings
+} from './navigation.js';
+// Playground types
+export type {
+  CodeGenerator,
+  CodeGeneratorConfig,
+  ControlCondition,
+  ControlDefinition,
+  ControlOption,
+  ControlType,
+  ImportStatement,
+  PlaygroundConfig,
+  PlaygroundExample,
+  PlaygroundFeature,
+  PlaygroundMetadata
+} from './playground.js';
+
+// ==========================================
+// BARREL EXPORTS
+// ==========================================
+
+export * from './component.js';
+export * from './docs-config.js';
+// Re-export everything for convenience (except documentation-core)
+export * from './documentation.js';
+export * from './examples.js';
+export * from './navigation.js';
+export * from './playground.js';

package/src/navigation.ts

@@ -0,0 +1,206 @@
+/**
+ * Navigation item
+ */
+export interface NavigationItem {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Navigation href/link */
+  href?: string;
+  /** Child navigation items */
+  children?: NavigationItem[];
+  /** Navigation metadata */
+  metadata?: NavigationMetadata;
+  /** Navigation state */
+  state?: NavigationState;
+}
+
+/**
+ * Navigation metadata
+ */
+export interface NavigationMetadata {
+  /** Item type */
+  type: 'section' | 'component' | 'group' | 'page' | 'external';
+  /** Navigation level/depth (migrated from level property) */
+  level?: number;
+  /** Display order */
+  order?: number;
+  /** Associated tags */
+  tags?: string[];
+  /** Icon identifier */
+  icon?: string;
+  /** Badge information */
+  badge?: NavigationBadge;
+}
+
+/**
+ * Navigation state
+ */
+export interface NavigationState {
+  /** Item is active/current */
+  active?: boolean;
+  /** Item is expanded (has visible children) */
+  expanded?: boolean;
+  /** Item is disabled */
+  disabled?: boolean;
+  /** Item is hidden */
+  hidden?: boolean;
+  /** Loading state */
+  loading?: boolean;
+}
+
+/**
+ * Navigation badge
+ */
+export interface NavigationBadge {
+  /** Badge text */
+  text: string;
+  /** Badge intent/color */
+  intent?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info';
+  /** Badge variant */
+  variant?: 'filled' | 'outlined' | 'soft';
+}
+
+/**
+ * Table of contents
+ */
+export interface TableOfContents {
+  /** TOC items */
+  items: TOCItem[];
+  /** TOC settings */
+  settings: TOCSettings;
+}
+
+/**
+ * Table of contents item
+ */
+export interface TOCItem {
+  /** Unique identifier */
+  id: string;
+  /** Item title */
+  title: string;
+  /** Heading level (1-6) */
+  level: number;
+  /** Anchor/fragment identifier */
+  anchor: string;
+  /** Child TOC items */
+  children?: TOCItem[];
+  /** Item section type */
+  sectionType?: 'overview' | 'examples' | 'api' | 'patterns' | 'custom';
+}
+
+/**
+ * TOC settings
+ */
+export interface TOCSettings {
+  /** Maximum depth to show */
+  maxDepth: number;
+  /** Highlight active item */
+  highlightActive?: boolean;
+  /** Collapse behavior */
+  collapsible?: boolean;
+}
+
+/**
+ * Breadcrumb navigation
+ */
+export interface Breadcrumb {
+  /** Breadcrumb items */
+  items: BreadcrumbItem[];
+  /** Breadcrumb settings */
+  settings?: BreadcrumbSettings;
+}
+
+/**
+ * Breadcrumb item
+ */
+export interface BreadcrumbItem {
+  /** Item label */
+  label: string;
+  /** Item href */
+  href?: string;
+  /** Item is current page */
+  current?: boolean;
+  /** Item icon */
+  icon?: string;
+}
+
+/**
+ * Breadcrumb settings
+ */
+export interface BreadcrumbSettings {
+  /** Maximum items to show */
+  maxItems?: number;
+  /** Show home link */
+  showHome?: boolean;
+  /** Separator character/element */
+  separator?: string;
+  /** Collapse behavior */
+  collapseThreshold?: number;
+}
+
+/**
+ * Site navigation structure
+ */
+export interface SiteNavigation {
+  /** Main navigation items */
+  main: NavigationItem[];
+  /** Footer navigation items */
+  footer?: NavigationItem[];
+  /** Utility navigation (user menu, etc.) */
+  utility?: NavigationItem[];
+  /** Mobile navigation settings */
+  mobile?: {
+    breakpoint?: number;
+    hamburgerMenu?: boolean;
+    collapsible?: boolean;
+  };
+}
+
+/**
+ * Navigation context for current page
+ */
+export interface NavigationContext {
+  /** Current page */
+  current: NavigationItem;
+  /** Parent page (if any) */
+  parent?: NavigationItem;
+  /** Previous page in sequence */
+  previous?: NavigationItem;
+  /** Next page in sequence */
+  next?: NavigationItem;
+  /** Breadcrumb trail */
+  breadcrumb: BreadcrumbItem[];
+  /** Related pages */
+  related?: NavigationItem[];
+}
+
+/**
+ * Navigation search result
+ */
+export interface NavigationSearchResult {
+  /** Matched navigation item */
+  item: NavigationItem;
+  /** Match score (0-1) */
+  score: number;
+  /** Matched text fragments */
+  matches: SearchMatch[];
+  /** Result metadata */
+  metadata?: {
+    searchTime?: number;
+    resultType?: 'exact' | 'fuzzy' | 'partial';
+  };
+}
+
+/**
+ * Search match information
+ */
+export interface SearchMatch {
+  /** Matched field */
+  field: 'label' | 'description' | 'content' | 'tags';
+  /** Matched text */
+  text: string;
+  /** Match indices */
+  indices: [number, number][];
+}

package/src/playground.ts

@@ -0,0 +1,184 @@
+/**
+ * Playground configuration
+ */
+export interface PlaygroundConfig {
+  /** Interactive controls */
+  controls: ControlDefinition[];
+  /** Code generator function */
+  codeGenerator?: CodeGenerator | CodeGeneratorConfig;
+  /** Default values for controls */
+  defaultValues?: Record<string, unknown>;
+  /** Playground examples/presets */
+  examples?: PlaygroundExample[];
+  /** Include in LLM output */
+  includeLLM?: boolean;
+  /** Playground metadata */
+  metadata?: PlaygroundMetadata;
+}
+
+/**
+ * Control definition for playground
+ */
+export interface ControlDefinition {
+  /** Control identifier */
+  key: string;
+  /** Control label */
+  label: string;
+  /** Control type */
+  type: ControlType;
+  /** Control options (for select/dropdown) */
+  items?: ControlOption[];
+  /** Default value */
+  defaultValue?: unknown;
+  /** Minimum value (for number/range) */
+  min?: number;
+  /** Maximum value (for number/range) */
+  max?: number;
+  /** Step value (for number/range) */
+  step?: number;
+  /** Placeholder text (for text inputs) */
+  placeholder?: string;
+  /** Control description */
+  description?: string;
+  /** Control group/category */
+  group?: string;
+  /** Control visibility condition */
+  condition?: ControlCondition;
+}
+
+/**
+ * Control types
+ */
+export type ControlType =
+  | 'dropdown'
+  | 'select'
+  | 'checkbox'
+  | 'boolean'
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'range'
+  | 'slider'
+  | 'color'
+  | 'radio'
+  | 'multi-select'
+  | 'json'
+  | 'code';
+
+/**
+ * Control option for select/dropdown controls
+ */
+export interface ControlOption {
+  /** Option label */
+  label: string;
+  /** Option value */
+  value: unknown;
+  /** Option description */
+  description?: string;
+  /** Option group */
+  group?: string;
+  /** Option disabled state */
+  disabled?: boolean;
+}
+
+/**
+ * Control visibility condition
+ */
+export interface ControlCondition {
+  /** Dependent control key. Optional when a custom `condition` function is provided. */
+  dependsOn?: string;
+  /** Expected value(s) */
+  equals?: unknown;
+  /** Value array (for 'in' condition) */
+  in?: unknown[];
+  /** Custom condition function */
+  condition?: (values: Record<string, unknown>) => boolean;
+}
+
+/**
+ * Code generator function type
+ */
+export type CodeGenerator = (values: Record<string, unknown>) => string;
+
+/**
+ * Code generator configuration
+ */
+export interface CodeGeneratorConfig {
+  /** Template string or function */
+  template: string | CodeGenerator;
+  /** Template variables */
+  variables?: Record<string, unknown>;
+  /** Import statements */
+  imports?: ImportStatement[];
+  /** Code formatting options */
+  formatting?: {
+    language?: 'typescript' | 'javascript' | 'svelte' | 'react';
+    prettier?: boolean;
+    indentation?: number;
+  };
+}
+
+/**
+ * Import statement for generated code
+ */
+export interface ImportStatement {
+  /** What to import */
+  imports: string | string[] | Record<string, string>;
+  /** From which module */
+  from: string;
+  /** Import type (default, named, namespace) */
+  type?: 'default' | 'named' | 'namespace';
+}
+
+/**
+ * Playground example/preset
+ */
+export interface PlaygroundExample {
+  /** Example title */
+  title: string;
+  /** Example description */
+  description?: string;
+  /** Control values for this example */
+  values: Record<string, unknown>;
+  /** Example category */
+  category?: 'basic' | 'advanced' | 'showcase' | 'use-case';
+  /** Example tags */
+  tags?: string[];
+}
+
+/**
+ * Playground metadata
+ */
+export interface PlaygroundMetadata {
+  /** Playground version */
+  version?: string;
+  /** Last updated */
+  lastUpdated?: string;
+  /** Playground features */
+  features?: PlaygroundFeature[];
+  /** Performance settings */
+  performance?: {
+    debounceMs?: number;
+    lazyLoad?: boolean;
+    cacheResults?: boolean;
+  };
+  /** Accessibility settings */
+  accessibility?: {
+    announceChanges?: boolean;
+    keyboardNavigation?: boolean;
+    focusManagement?: boolean;
+  };
+}
+
+/**
+ * Playground features
+ */
+export type PlaygroundFeature =
+  | 'live-preview'
+  | 'code-generation'
+  | 'export-code'
+  | 'share-link'
+  | 'responsive-preview'
+  | 'dark-mode'
+  | 'accessibility-checker'
+  | 'performance-monitor';