freesail 0.0.1 → 0.1.0

package/packages/lit-ui/src/catalogs/standard/elements/Select.ts

@@ -0,0 +1,110 @@
+/**
+ * Select Component
+ * 
+ * A dropdown select with options.
+ */
+
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+interface SelectOption {
+  value: string;
+  label: string;
+}
+
+@customElement('fs-select')
+export class FreesailSelect extends LitElement {
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    .select-wrapper {
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+    }
+
+    label {
+      font-size: 0.875rem;
+      font-weight: 500;
+      color: #374151;
+    }
+
+    select {
+      font-family: inherit;
+      font-size: 1rem;
+      padding: 10px 12px;
+      border: 1px solid #d1d5db;
+      border-radius: 6px;
+      outline: none;
+      background: white;
+      cursor: pointer;
+      transition: border-color 0.2s ease, box-shadow 0.2s ease;
+    }
+
+    select:focus {
+      border-color: #2563eb;
+      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.1);
+    }
+
+    select:disabled {
+      background: #f3f4f6;
+      cursor: not-allowed;
+    }
+  `;
+
+  @property({ type: String }) value = '';
+  @property({ type: Array }) options: SelectOption[] = [];
+  @property({ type: String }) placeholder = 'Select an option';
+  @property({ type: String }) label = '';
+  @property({ type: Boolean }) disabled = false;
+  @property({ type: String }) bindPath = '';
+
+  private handleChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    this.value = select.value;
+
+    this.dispatchEvent(new CustomEvent('fs-change', {
+      bubbles: true,
+      composed: true,
+      detail: {
+        value: this.value,
+        bindPath: this.bindPath,
+        componentId: this.id,
+      }
+    }));
+  }
+
+  override render() {
+    return html`
+      <div class="select-wrapper">
+        ${this.label ? html`<label>${this.label}</label>` : ''}
+        
+        <select
+          .value=${this.value}
+          ?disabled=${this.disabled}
+          @change=${this.handleChange}
+        >
+          <option value="" disabled ?selected=${!this.value}>
+            ${this.placeholder}
+          </option>
+          ${this.options.map(opt => html`
+            <option 
+              value=${opt.value} 
+              ?selected=${opt.value === this.value}
+            >
+              ${opt.label}
+            </option>
+          `)}
+        </select>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'fs-select': FreesailSelect;
+  }
+}

package/packages/lit-ui/src/catalogs/standard/elements/Spacer.ts

@@ -0,0 +1,37 @@
+/**
+ * Spacer Component
+ * 
+ * A flexible space component for layout.
+ */
+
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+@customElement('fs-spacer')
+export class FreesailSpacer extends LitElement {
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    .spacer.flex {
+      flex: 1;
+    }
+  `;
+
+  @property({ type: String }) size = 'flex';
+
+  override render() {
+    if (this.size === 'flex') {
+      return html`<div class="spacer flex"></div>`;
+    }
+
+    return html`<div class="spacer" style="height: ${this.size}; width: ${this.size}"></div>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'fs-spacer': FreesailSpacer;
+  }
+}

package/packages/lit-ui/src/catalogs/standard/elements/Spinner.ts

@@ -0,0 +1,76 @@
+/**
+ * Spinner Component
+ * 
+ * A loading spinner indicator.
+ */
+
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+type SpinnerSize = 'small' | 'medium' | 'large';
+
+@customElement('fs-spinner')
+export class FreesailSpinner extends LitElement {
+  static override styles = css`
+    :host {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .spinner {
+      border-radius: 50%;
+      border-style: solid;
+      border-color: currentColor;
+      border-top-color: transparent;
+      animation: spin 0.8s linear infinite;
+    }
+
+    .size-small {
+      width: 16px;
+      height: 16px;
+      border-width: 2px;
+    }
+
+    .size-medium {
+      width: 24px;
+      height: 24px;
+      border-width: 3px;
+    }
+
+    .size-large {
+      width: 36px;
+      height: 36px;
+      border-width: 4px;
+    }
+
+    @keyframes spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+  `;
+
+  @property({ type: String }) size: SpinnerSize = 'medium';
+  @property({ type: String }) color = 'currentColor';
+
+  override render() {
+    const classes = `spinner size-${this.size}`;
+    const style = `color: ${this.color}`;
+
+    return html`
+      <div 
+        class=${classes}
+        style=${style}
+        role="status"
+        aria-label="Loading"
+      ></div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'fs-spinner': FreesailSpinner;
+  }
+}

package/packages/lit-ui/src/catalogs/standard/elements/Text.ts

@@ -0,0 +1,86 @@
+/**
+ * Text Component
+ * 
+ * A text display component with variant styles.
+ */
+
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'body' | 'caption' | 'overline';
+type FontWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+
+@customElement('fs-text')
+export class FreesailText extends LitElement {
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    .text {
+      margin: 0;
+      font-family: inherit;
+    }
+
+    .h1 { font-size: 2.5rem; line-height: 1.2; }
+    .h2 { font-size: 2rem; line-height: 1.25; }
+    .h3 { font-size: 1.75rem; line-height: 1.3; }
+    .h4 { font-size: 1.5rem; line-height: 1.35; }
+    .h5 { font-size: 1.25rem; line-height: 1.4; }
+    .h6 { font-size: 1rem; line-height: 1.45; }
+    .body { font-size: 1rem; line-height: 1.5; }
+    .caption { font-size: 0.875rem; line-height: 1.4; }
+    .overline { 
+      font-size: 0.75rem; 
+      line-height: 1.4; 
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+    }
+
+    .weight-light { font-weight: 300; }
+    .weight-normal { font-weight: 400; }
+    .weight-medium { font-weight: 500; }
+    .weight-semibold { font-weight: 600; }
+    .weight-bold { font-weight: 700; }
+
+    .align-left { text-align: left; }
+    .align-center { text-align: center; }
+    .align-right { text-align: right; }
+    .align-justify { text-align: justify; }
+  `;
+
+  @property({ type: String }) text = '';
+  @property({ type: String }) variant: TextVariant = 'body';
+  @property({ type: String }) color = 'inherit';
+  @property({ type: String }) weight: FontWeight = 'normal';
+  @property({ type: String }) align = 'left';
+
+  override render() {
+    const classes = `text ${this.variant} weight-${this.weight} align-${this.align}`;
+    const style = `color: ${this.color}`;
+
+    // Use appropriate semantic element
+    switch (this.variant) {
+      case 'h1':
+        return html`<h1 class=${classes} style=${style}>${this.text}</h1>`;
+      case 'h2':
+        return html`<h2 class=${classes} style=${style}>${this.text}</h2>`;
+      case 'h3':
+        return html`<h3 class=${classes} style=${style}>${this.text}</h3>`;
+      case 'h4':
+        return html`<h4 class=${classes} style=${style}>${this.text}</h4>`;
+      case 'h5':
+        return html`<h5 class=${classes} style=${style}>${this.text}</h5>`;
+      case 'h6':
+        return html`<h6 class=${classes} style=${style}>${this.text}</h6>`;
+      default:
+        return html`<p class=${classes} style=${style}>${this.text}</p>`;
+    }
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'fs-text': FreesailText;
+  }
+}

package/packages/lit-ui/src/catalogs/standard/elements/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Standard Catalog Elements Index
+ */
+
+export { FreesailColumn } from './Column.js';
+export { FreesailRow } from './Row.js';
+export { FreesailText } from './Text.js';
+export { FreesailButton } from './Button.js';
+export { FreesailInput } from './Input.js';
+export { FreesailCard } from './Card.js';
+export { FreesailImage } from './Image.js';
+export { FreesailDivider } from './Divider.js';
+export { FreesailSpacer } from './Spacer.js';
+export { FreesailBadge } from './Badge.js';
+export { FreesailCheckbox } from './Checkbox.js';
+export { FreesailSelect } from './Select.js';
+export { FreesailSpinner } from './Spinner.js';
+export { FreesailProgress } from './Progress.js';

package/packages/lit-ui/src/catalogs/standard/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Standard Catalog
+ * 
+ * Exports the standard A2UI catalog with all components.
+ */
+
+import catalog from './catalog.json';
+import type { CatalogDefinition } from '../../types.js';
+
+// Import all elements to register them
+export * from './elements/index.js';
+
+// Export catalog definition
+export const standardCatalog = catalog as unknown as CatalogDefinition;
+
+// Export catalog ID for convenience
+export const STANDARD_CATALOG_ID = 'standard_catalog_v1';

package/packages/lit-ui/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Freesail Lit UI
+ * 
+ * Web Components library for A2UX Protocol rendering.
+ */
+
+// Types
+export type { CatalogDefinition, ComponentDefinition, PropertyDefinition, RendererConfig } from './types.js';
+
+// Utils
+export { defineProps, getDefaults, validateProps } from './utils/define-props.js';
+export { ComponentRegistry, registry } from './utils/registry.js';
+
+// Renderer
+export { SurfaceRenderer, createSurfaceRenderer } from './renderer.js';
+export type { SurfaceRendererOptions } from './renderer.js';
+
+// Standard Catalog
+export { 
+  standardCatalog, 
+  STANDARD_CATALOG_ID,
+  FreesailColumn,
+  FreesailRow,
+  FreesailText,
+  FreesailButton,
+  FreesailInput,
+  FreesailCard,
+  FreesailImage,
+  FreesailDivider,
+  FreesailSpacer,
+  FreesailBadge,
+  FreesailCheckbox,
+  FreesailSelect,
+  FreesailSpinner,
+  FreesailProgress,
+} from './catalogs/standard/index.js';
+
+// =============================================================================
+// Setup Helper
+// =============================================================================
+
+import { registry } from './utils/registry.js';
+import { standardCatalog, STANDARD_CATALOG_ID } from './catalogs/standard/index.js';
+import type { LitElement } from 'lit';
+
+// Import element classes for registration
+import { FreesailColumn } from './catalogs/standard/elements/Column.js';
+import { FreesailRow } from './catalogs/standard/elements/Row.js';
+import { FreesailText } from './catalogs/standard/elements/Text.js';
+import { FreesailButton } from './catalogs/standard/elements/Button.js';
+import { FreesailInput } from './catalogs/standard/elements/Input.js';
+import { FreesailCard } from './catalogs/standard/elements/Card.js';
+import { FreesailImage } from './catalogs/standard/elements/Image.js';
+import { FreesailDivider } from './catalogs/standard/elements/Divider.js';
+import { FreesailSpacer } from './catalogs/standard/elements/Spacer.js';
+import { FreesailBadge } from './catalogs/standard/elements/Badge.js';
+import { FreesailCheckbox } from './catalogs/standard/elements/Checkbox.js';
+import { FreesailSelect } from './catalogs/standard/elements/Select.js';
+import { FreesailSpinner } from './catalogs/standard/elements/Spinner.js';
+import { FreesailProgress } from './catalogs/standard/elements/Progress.js';
+
+/**
+ * Register the standard catalog with all components
+ */
+export function registerStandardCatalog(): void {
+  const components = new Map<string, typeof LitElement>([
+    ['Column', FreesailColumn],
+    ['Row', FreesailRow],
+    ['Text', FreesailText],
+    ['Button', FreesailButton],
+    ['Input', FreesailInput],
+    ['Card', FreesailCard],
+    ['Image', FreesailImage],
+    ['Divider', FreesailDivider],
+    ['Spacer', FreesailSpacer],
+    ['Badge', FreesailBadge],
+    ['Checkbox', FreesailCheckbox],
+    ['Select', FreesailSelect],
+    ['Spinner', FreesailSpinner],
+    ['Progress', FreesailProgress],
+  ]);
+
+  registry.registerCatalog(STANDARD_CATALOG_ID, standardCatalog, components, 'fs');
+}

package/packages/lit-ui/src/renderer.ts

@@ -0,0 +1,211 @@
+/**
+ * Surface Renderer
+ * 
+ * Renders A2UX surfaces to the DOM using registered Web Components.
+ */
+
+import { html, render, TemplateResult } from 'lit';
+import type { A2UXComponent, SurfaceStore, Surface } from '@freesail/core';
+import { registry } from './utils/registry.js';
+
+export interface SurfaceRendererOptions {
+  /** Target container element or selector */
+  container: HTMLElement | string;
+  /** Surface ID to render */
+  surfaceId: string;
+  /** Store instance */
+  store: SurfaceStore;
+  /** Enable debug mode */
+  debug?: boolean;
+}
+
+/**
+ * SurfaceRenderer dynamically renders A2UX surfaces to the DOM.
+ * It subscribes to store changes and re-renders automatically.
+ */
+export class SurfaceRenderer {
+  private container: HTMLElement;
+  private surfaceId: string;
+  private store: SurfaceStore;
+  private debug: boolean;
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(options: SurfaceRendererOptions) {
+    // Resolve container
+    if (typeof options.container === 'string') {
+      const el = document.querySelector(options.container);
+      if (!el) {
+        throw new Error(`Container not found: ${options.container}`);
+      }
+      this.container = el as HTMLElement;
+    } else {
+      this.container = options.container;
+    }
+
+    this.surfaceId = options.surfaceId;
+    this.store = options.store;
+    this.debug = options.debug ?? false;
+
+    // Subscribe to surface changes
+    this.unsubscribe = this.store.subscribeSurface(this.surfaceId, () => {
+      this.render();
+    });
+
+    // Initial render
+    this.render();
+  }
+
+  /**
+   * Render the surface to the container
+   */
+  render(): void {
+    const surface = this.store.getSurface(this.surfaceId);
+    
+    if (!surface) {
+      this.log(`Surface not found: ${this.surfaceId}`);
+      render(html``, this.container);
+      return;
+    }
+
+    const rootComponent = this.store.getRootComponent(this.surfaceId);
+    
+    if (!rootComponent) {
+      this.log(`No root component for surface: ${this.surfaceId}`);
+      render(html``, this.container);
+      return;
+    }
+
+    const template = this.renderComponent(rootComponent, surface);
+    render(template, this.container);
+    
+    this.log(`Rendered surface: ${this.surfaceId}`);
+  }
+
+  /**
+   * Render a single component and its children
+   */
+  private renderComponent(component: A2UXComponent, surface: Surface): TemplateResult {
+    const tagName = registry.getTagNameForCatalog(surface.catalogId, component.component);
+    
+    if (!tagName) {
+      this.log(`Component not registered: ${component.component}`);
+      return html`<!-- Unknown component: ${component.component} -->`;
+    }
+
+    // Build children templates
+    let childTemplates: TemplateResult[] = [];
+    
+    if (component.children && Array.isArray(component.children)) {
+      childTemplates = component.children.map(childId => {
+        const child = this.store.getComponent(this.surfaceId, childId as string);
+        if (child) {
+          return this.renderComponent(child, surface);
+        }
+        return html`<!-- Missing child: ${childId} -->`;
+      });
+    }
+
+    // Extract component properties (exclude id, component, children)
+    const { id: _id, component: _component, children: _children, ...props } = component;
+
+    // Apply data model bindings
+    this.applyDataBindings(props, surface);
+
+    // Create element dynamically
+    return this.createDynamicElement(tagName, props, childTemplates, component.id);
+  }
+
+  /**
+   * Apply data model bindings to properties
+   */
+  private applyDataBindings(props: Record<string, unknown>, surface: Surface): void {
+    for (const [key, value] of Object.entries(props)) {
+      if (typeof value === 'string' && value.startsWith('$data:')) {
+        const path = value.slice(6); // Remove '$data:' prefix
+        props[key] = this.store.getDataValue(surface.surfaceId, path);
+      }
+    }
+  }
+
+  /**
+   * Create a dynamic element with properties
+   */
+  private createDynamicElement(
+    tagName: string, 
+    props: Record<string, unknown>,
+    children: TemplateResult[],
+    id: string
+  ): TemplateResult {
+    // Convert props to attribute format for Lit
+    const propEntries = Object.entries(props);
+    
+    // Build props string for logging
+    const propsStr = propEntries
+      .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+      .join(' ');
+    
+    this.log(`Creating <${tagName} ${propsStr}>`);
+
+    // Use unsafeStatic for dynamic tag names requires lit-html/static
+    // For simplicity, we'll use document.createElement approach
+    const el = document.createElement(tagName);
+    el.id = id;
+    
+    // Set properties
+    for (const [key, value] of propEntries) {
+      if (value !== undefined && value !== null) {
+        (el as unknown as Record<string, unknown>)[key] = value;
+      }
+    }
+
+    // Render children into slot
+    if (children.length > 0) {
+      const childContainer = document.createElement('div');
+      render(html`${children}`, childContainer);
+      while (childContainer.firstChild) {
+        el.appendChild(childContainer.firstChild);
+      }
+    }
+
+    // Return as template
+    return html`${el}`;
+  }
+
+  /**
+   * Update a specific component without full re-render
+   */
+  updateComponent(_componentId: string): void {
+    // For now, just do a full re-render
+    // Future optimization: targeted DOM updates
+    this.render();
+  }
+
+  /**
+   * Destroy the renderer and cleanup
+   */
+  destroy(): void {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    
+    // Clear container
+    this.container.innerHTML = '';
+  }
+
+  /**
+   * Debug logging
+   */
+  private log(message: string): void {
+    if (this.debug) {
+      console.log(`[SurfaceRenderer:${this.surfaceId}] ${message}`);
+    }
+  }
+}
+
+/**
+ * Create a surface renderer instance
+ */
+export function createSurfaceRenderer(options: SurfaceRendererOptions): SurfaceRenderer {
+  return new SurfaceRenderer(options);
+}

package/packages/lit-ui/src/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Freesail Lit UI Types
+ */
+
+/**
+ * Property definition in a catalog
+ */
+export interface PropertyDefinition {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  description?: string;
+  default?: unknown;
+  enum?: string[];
+  reflect?: boolean;
+  required?: boolean;
+}
+
+/**
+ * Component definition in a catalog
+ */
+export interface ComponentDefinition {
+  description?: string;
+  properties?: Record<string, PropertyDefinition>;
+  required?: string[];
+  slots?: Record<string, { description?: string }>;
+  events?: Record<string, { description?: string }>;
+}
+
+/**
+ * Catalog definition structure
+ */
+export interface CatalogDefinition {
+  id: string;
+  version: string;
+  name?: string;
+  description?: string;
+  components: Record<string, ComponentDefinition>;
+}
+
+/**
+ * Surface renderer configuration
+ */
+export interface RendererConfig {
+  /** Target container element */
+  container: HTMLElement;
+  /** Catalog ID to use */
+  catalogId: string;
+  /** Enable debug mode */
+  debug?: boolean;
+}