@object-ui/core 3.0.3 → 3.1.0

package/src/protocols/DndProtocol.ts

@@ -0,0 +1,184 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @object-ui/core - DnD Protocol Bridge
+ *
+ * Converts spec-aligned DnD configuration schemas into runtime-usable
+ * component props and CSS constraint styles for drag-and-drop interactions.
+ *
+ * @module protocols/DndProtocol
+ * @packageDocumentation
+ */
+
+import type { DndConfig, DragItem, DropZone, DragConstraint } from '@object-ui/types';
+
+// ============================================================================
+// Resolved Types
+// ============================================================================
+
+/** Fully resolved DnD configuration with all defaults applied. */
+export interface ResolvedDndConfig {
+  enabled: boolean;
+  sortable: boolean;
+  autoScroll: boolean;
+  touchDelay: number;
+  dragItem?: DragItem;
+  dropZone?: DropZone;
+}
+
+/** Component props for a draggable element. */
+export interface DragItemProps {
+  draggable: boolean;
+  'aria-roledescription': string;
+  'aria-label'?: string;
+  'aria-describedby'?: string;
+  role: string;
+  'data-drag-type': string;
+  'data-drag-handle': string;
+  'data-drag-disabled': string;
+}
+
+/** Component props for a droppable area. */
+export interface DropZoneProps {
+  'aria-dropeffect': string;
+  'aria-label'?: string;
+  'aria-describedby'?: string;
+  role: string;
+  'data-drop-accept': string;
+  'data-drop-max-items'?: number;
+  'data-drop-highlight': string;
+}
+
+/** CSS constraint styles for drag movement. */
+export interface DragConstraintStyles {
+  position: string;
+  touchAction: string;
+  [key: string]: string | number | undefined;
+}
+
+// ============================================================================
+// DnD Config Resolution
+// ============================================================================
+
+/**
+ * Resolve a DnD configuration by applying spec defaults to missing fields.
+ *
+ * @param config - Partial DnD configuration from the spec
+ * @returns Fully resolved DnD configuration
+ */
+export function resolveDndConfig(config: DndConfig): ResolvedDndConfig {
+  return {
+    enabled: config.enabled ?? false,
+    sortable: config.sortable ?? false,
+    autoScroll: config.autoScroll ?? true,
+    touchDelay: config.touchDelay ?? 200,
+    dragItem: config.dragItem,
+    dropZone: config.dropZone,
+  };
+}
+
+// ============================================================================
+// Drag Item Props
+// ============================================================================
+
+/**
+ * Convert a spec DragItem to component props suitable for a draggable element.
+ * Produces `draggable`, ARIA attributes, and data attributes for DnD libraries.
+ *
+ * @param item - DragItem configuration from the spec
+ * @returns Component props object for a draggable element
+ */
+export function createDragItemProps(item: DragItem): DragItemProps {
+  const ariaLabel = typeof item.ariaLabel === 'string'
+    ? item.ariaLabel
+    : item.ariaLabel?.defaultValue;
+
+  const label = typeof item.label === 'string'
+    ? item.label
+    : item.label?.defaultValue;
+
+  return {
+    draggable: !(item.disabled ?? false),
+    'aria-roledescription': 'draggable',
+    'aria-label': ariaLabel ?? label,
+    'aria-describedby': item.ariaDescribedBy,
+    role: item.role ?? 'listitem',
+    'data-drag-type': item.type,
+    'data-drag-handle': item.handle ?? 'element',
+    'data-drag-disabled': String(item.disabled ?? false),
+  };
+}
+
+// ============================================================================
+// Drop Zone Props
+// ============================================================================
+
+/**
+ * Convert a spec DropZone to component props suitable for a droppable area.
+ * Produces ARIA attributes and data attributes for DnD libraries.
+ *
+ * @param zone - DropZone configuration from the spec
+ * @returns Component props object for a droppable area
+ */
+export function createDropZoneProps(zone: DropZone): DropZoneProps {
+  const ariaLabel = typeof zone.ariaLabel === 'string'
+    ? zone.ariaLabel
+    : zone.ariaLabel?.defaultValue;
+
+  const label = typeof zone.label === 'string'
+    ? zone.label
+    : zone.label?.defaultValue;
+
+  return {
+    'aria-dropeffect': zone.dropEffect ?? 'move',
+    'aria-label': ariaLabel ?? label,
+    'aria-describedby': zone.ariaDescribedBy,
+    role: zone.role ?? 'list',
+    'data-drop-accept': zone.accept.join(','),
+    'data-drop-max-items': zone.maxItems,
+    'data-drop-highlight': String(zone.highlightOnDragOver ?? true),
+  };
+}
+
+// ============================================================================
+// Drag Constraint Styles
+// ============================================================================
+
+/**
+ * Resolve a DragConstraint into CSS style properties that restrict
+ * drag movement along an axis or within bounds.
+ *
+ * @param constraint - DragConstraint configuration from the spec
+ * @returns CSS styles object for constraining drag movement
+ */
+export function resolveDragConstraints(constraint: DragConstraint): DragConstraintStyles {
+  const styles: DragConstraintStyles = {
+    position: 'relative',
+    touchAction: 'none',
+  };
+
+  const axis = constraint.axis ?? 'both';
+  if (axis === 'x') {
+    styles.touchAction = 'pan-y';
+  } else if (axis === 'y') {
+    styles.touchAction = 'pan-x';
+  }
+
+  const bounds = constraint.bounds ?? 'none';
+  if (bounds === 'parent') {
+    styles.overflow = 'hidden';
+  }
+
+  if (constraint.grid) {
+    styles['--drag-grid-x'] = `${constraint.grid[0]}px`;
+    styles['--drag-grid-y'] = `${constraint.grid[1]}px`;
+  }
+
+  return styles;
+}

package/src/protocols/KeyboardProtocol.ts

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @object-ui/core - Keyboard Protocol Bridge
+ *
+ * Converts spec-aligned keyboard navigation and focus management
+ * schemas into runtime-usable configurations, shortcut parsers,
+ * and focus trap settings.
+ *
+ * @module protocols/KeyboardProtocol
+ * @packageDocumentation
+ */
+
+import type {
+  KeyboardNavigationConfig,
+  KeyboardShortcut,
+  FocusManagement,
+  FocusTrapConfig,
+} from '@object-ui/types';
+
+// ============================================================================
+// Resolved Types
+// ============================================================================
+
+/** Fully resolved keyboard navigation configuration. */
+export interface ResolvedKeyboardConfig {
+  shortcuts: KeyboardShortcut[];
+  focusManagement: ResolvedFocusManagement;
+  rovingTabindex: boolean;
+  ariaLabel?: string;
+  ariaDescribedBy?: string;
+  role?: string;
+}
+
+/** Fully resolved focus management configuration. */
+export interface ResolvedFocusManagement {
+  tabOrder: 'auto' | 'manual';
+  skipLinks: boolean;
+  focusVisible: boolean;
+  focusTrap?: ResolvedFocusTrapConfig;
+  arrowNavigation: boolean;
+}
+
+/** Fully resolved focus trap configuration. */
+export interface ResolvedFocusTrapConfig {
+  enabled: boolean;
+  initialFocus?: string;
+  returnFocus: boolean;
+  escapeDeactivates: boolean;
+}
+
+/** Parsed keyboard shortcut descriptor. */
+export interface ParsedShortcut {
+  key: string;
+  ctrlOrMeta: boolean;
+  shift: boolean;
+  alt: boolean;
+}
+
+/** Minimal keyboard event shape for matching (no React dependency). */
+export interface KeyboardEventLike {
+  key: string;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+}
+
+// ============================================================================
+// Keyboard Config Resolution
+// ============================================================================
+
+/**
+ * Resolve a keyboard navigation configuration by applying spec defaults.
+ *
+ * @param config - KeyboardNavigationConfig from the spec
+ * @returns Fully resolved keyboard navigation configuration
+ */
+export function resolveKeyboardConfig(config: KeyboardNavigationConfig): ResolvedKeyboardConfig {
+  const ariaLabel = typeof config.ariaLabel === 'string'
+    ? config.ariaLabel
+    : config.ariaLabel?.defaultValue;
+
+  return {
+    shortcuts: config.shortcuts ?? [],
+    focusManagement: resolveFocusManagement(config.focusManagement),
+    rovingTabindex: config.rovingTabindex ?? false,
+    ariaLabel,
+    ariaDescribedBy: config.ariaDescribedBy,
+    role: config.role,
+  };
+}
+
+/**
+ * Resolve focus management configuration with defaults.
+ */
+function resolveFocusManagement(fm?: FocusManagement): ResolvedFocusManagement {
+  return {
+    tabOrder: fm?.tabOrder ?? 'auto',
+    skipLinks: fm?.skipLinks ?? false,
+    focusVisible: fm?.focusVisible ?? true,
+    focusTrap: fm?.focusTrap ? createFocusTrapConfig(fm.focusTrap) : undefined,
+    arrowNavigation: fm?.arrowNavigation ?? false,
+  };
+}
+
+// ============================================================================
+// Shortcut Parsing
+// ============================================================================
+
+/**
+ * Parse a shortcut string like "Ctrl+Shift+S" into a structured descriptor.
+ * Recognises Ctrl, Meta, Cmd (mapped to ctrlOrMeta), Shift, and Alt modifiers.
+ * The last segment is treated as the key.
+ *
+ * Keys are normalised to lowercase for case-insensitive matching. The Shift
+ * modifier is tracked separately, so "Shift+A" and "Shift+a" are equivalent
+ * (both represent the same physical key combination).
+ *
+ * @param shortcut - Shortcut string (e.g. "Ctrl+S", "Alt+Shift+N", "Escape")
+ * @returns Parsed shortcut descriptor
+ */
+export function parseShortcutKey(shortcut: string): ParsedShortcut {
+  const parts = shortcut.split('+').map(p => p.trim());
+  const modifiers = new Set(parts.slice(0, -1).map(m => m.toLowerCase()));
+  const key = (parts[parts.length - 1] ?? '').toLowerCase();
+
+  return {
+    key,
+    ctrlOrMeta: modifiers.has('ctrl') || modifiers.has('meta') || modifiers.has('cmd'),
+    shift: modifiers.has('shift'),
+    alt: modifiers.has('alt'),
+  };
+}
+
+// ============================================================================
+// Shortcut Matching
+// ============================================================================
+
+/**
+ * Test whether a keyboard event matches a shortcut string.
+ * Comparison is case-insensitive; the Shift modifier is checked separately.
+ *
+ * @param event - The keyboard event (or a plain object with key + modifier flags)
+ * @param shortcut - Shortcut string (e.g. "Ctrl+S")
+ * @returns `true` if the event matches the shortcut
+ */
+export function matchesShortcut(event: KeyboardEventLike, shortcut: string): boolean {
+  const parsed = parseShortcutKey(shortcut);
+
+  if (event.key.toLowerCase() !== parsed.key) return false;
+
+  const eventCtrlOrMeta = !!(event.ctrlKey || event.metaKey);
+  if (parsed.ctrlOrMeta !== eventCtrlOrMeta) return false;
+
+  if (parsed.shift !== !!(event.shiftKey)) return false;
+  if (parsed.alt !== !!(event.altKey)) return false;
+
+  return true;
+}
+
+// ============================================================================
+// Focus Trap Configuration
+// ============================================================================
+
+/**
+ * Create a resolved focus trap configuration from a spec FocusTrapConfig.
+ *
+ * @param config - FocusTrapConfig from the spec
+ * @returns Resolved focus trap configuration with defaults applied
+ */
+export function createFocusTrapConfig(config: FocusTrapConfig): ResolvedFocusTrapConfig {
+  return {
+    enabled: config.enabled ?? false,
+    initialFocus: config.initialFocus,
+    returnFocus: config.returnFocus ?? true,
+    escapeDeactivates: config.escapeDeactivates ?? true,
+  };
+}

package/src/protocols/NotificationProtocol.ts

@@ -0,0 +1,159 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @object-ui/core - Notification Protocol Bridge
+ *
+ * Converts spec-aligned Notification schemas into toast-compatible
+ * objects that UI layers can render. Maps severity to variant,
+ * position names, and resolves default notification configs.
+ *
+ * @module protocols/NotificationProtocol
+ * @packageDocumentation
+ */
+
+import type {
+  Notification as SpecNotification,
+  NotificationAction,
+  NotificationConfig,
+  NotificationPosition,
+  NotificationSeverity,
+} from '@object-ui/types';
+
+// ============================================================================
+// Resolved Types
+// ============================================================================
+
+/** Fully resolved notification configuration. */
+export interface ResolvedNotificationConfig {
+  defaultPosition: NotificationPosition;
+  defaultDuration: number;
+  maxVisible: number;
+  stackDirection: 'up' | 'down';
+  pauseOnHover: boolean;
+}
+
+/** Toast-compatible representation of a spec Notification. */
+export interface ToastNotification {
+  title?: string;
+  description: string;
+  variant: string;
+  position: string;
+  duration: number;
+  dismissible: boolean;
+  actions: ToastAction[];
+}
+
+/** Toast-compatible action button. */
+export interface ToastAction {
+  label: string;
+  action: string;
+  variant: 'primary' | 'secondary' | 'link';
+}
+
+// ============================================================================
+// Severity → Variant Mapping
+// ============================================================================
+
+const SEVERITY_TO_VARIANT: Record<string, string> = {
+  info: 'default',
+  success: 'success',
+  warning: 'warning',
+  error: 'destructive',
+};
+
+/**
+ * Map a spec notification severity to a toast variant string.
+ *
+ * @param severity - Spec severity (info, success, warning, error)
+ * @returns Toast variant (default, success, warning, destructive)
+ */
+export function mapSeverityToVariant(severity: string): string {
+  return SEVERITY_TO_VARIANT[severity] ?? 'default';
+}
+
+// ============================================================================
+// Position Mapping
+// ============================================================================
+
+const POSITION_MAP: Record<string, string> = {
+  top_left: 'top-left',
+  top_center: 'top-center',
+  top_right: 'top-right',
+  bottom_left: 'bottom-left',
+  bottom_center: 'bottom-center',
+  bottom_right: 'bottom-right',
+};
+
+/**
+ * Map a spec notification position (underscore-separated) to a
+ * toast position string (hyphen-separated).
+ *
+ * @param position - Spec position (e.g. "top_right")
+ * @returns Toast position (e.g. "top-right")
+ */
+export function mapPosition(position: string): string {
+  return POSITION_MAP[position] ?? 'top-right';
+}
+
+// ============================================================================
+// Notification Config Resolution
+// ============================================================================
+
+/**
+ * Resolve a notification configuration by applying spec defaults.
+ *
+ * @param config - NotificationConfig from the spec
+ * @returns Fully resolved notification configuration
+ */
+export function resolveNotificationConfig(config: NotificationConfig): ResolvedNotificationConfig {
+  return {
+    defaultPosition: config.defaultPosition ?? 'top_right',
+    defaultDuration: config.defaultDuration ?? 5000,
+    maxVisible: config.maxVisible ?? 5,
+    stackDirection: config.stackDirection ?? 'down',
+    pauseOnHover: config.pauseOnHover ?? true,
+  };
+}
+
+// ============================================================================
+// Spec Notification → Toast
+// ============================================================================
+
+/**
+ * Extract the display string from a translatable value (string or Translation object).
+ */
+function resolveTranslatableString(value: string | { key: string; defaultValue?: string } | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') return value;
+  return value.defaultValue;
+}
+
+/**
+ * Convert a spec Notification to a toast-compatible object.
+ *
+ * @param notification - Spec Notification
+ * @returns Toast-compatible notification with title, description, variant, etc.
+ */
+export function specNotificationToToast(notification: SpecNotification): ToastNotification {
+  const actions: ToastAction[] = (notification.actions ?? []).map((a: NotificationAction) => ({
+    label: typeof a.label === 'string' ? a.label : a.label?.defaultValue ?? '',
+    action: a.action,
+    variant: a.variant ?? 'primary',
+  }));
+
+  return {
+    title: resolveTranslatableString(notification.title),
+    description: resolveTranslatableString(notification.message) ?? '',
+    variant: mapSeverityToVariant(notification.severity ?? 'info'),
+    position: mapPosition(notification.position ?? 'top_right'),
+    duration: notification.duration ?? 5000,
+    dismissible: notification.dismissible ?? true,
+    actions,
+  };
+}