@object-ui/core 3.3.0 → 3.3.2

package/src/protocols/KeyboardProtocol.ts

@@ -1,181 +0,0 @@
-/**
- * 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 {
-  return {
-    shortcuts: config.shortcuts ?? [],
-    focusManagement: resolveFocusManagement(config.focusManagement),
-    rovingTabindex: config.rovingTabindex ?? false,
-    ariaLabel: config.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

@@ -1,150 +0,0 @@
-/**
- * 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
-// ============================================================================
-
-/**
- * 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: a.label,
-    action: a.action,
-    variant: a.variant ?? 'primary',
-  }));
-
-  return {
-    title: notification.title,
-    description: notification.message ?? '',
-    variant: mapSeverityToVariant(notification.severity ?? 'info'),
-    position: mapPosition(notification.position ?? 'top_right'),
-    duration: notification.duration ?? 5000,
-    dismissible: notification.dismissible ?? true,
-    actions,
-  };
-}

package/src/protocols/ResponsiveProtocol.ts

@@ -1,210 +0,0 @@
-/**
- * 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 - Responsive Protocol Bridge
- *
- * Converts spec-aligned ResponsiveConfig schemas into Tailwind CSS
- * utility classes for visibility, grid columns, and ordering across
- * breakpoints. Also provides runtime width-based visibility checks.
- *
- * @module protocols/ResponsiveProtocol
- * @packageDocumentation
- */
-
-import type { SpecResponsiveConfig } from '@object-ui/types';
-
-// ============================================================================
-// Breakpoint Definitions
-// ============================================================================
-
-/** Breakpoint name type matching Tailwind defaults. */
-export type BreakpointKey = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
-
-/** Breakpoint minimum pixel widths aligned with Tailwind CSS defaults. */
-export const BREAKPOINT_VALUES: Record<BreakpointKey, number> = {
-  xs: 0,
-  sm: 640,
-  md: 768,
-  lg: 1024,
-  xl: 1280,
-  '2xl': 1536,
-};
-
-/** Ordered breakpoint keys from smallest to largest. */
-const BREAKPOINT_ORDER: BreakpointKey[] = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'];
-
-// ============================================================================
-// Resolved Types
-// ============================================================================
-
-/** Fully resolved responsive configuration. */
-export interface ResolvedResponsiveConfig {
-  breakpoint?: BreakpointKey;
-  hiddenOn: BreakpointKey[];
-  columns: Partial<Record<BreakpointKey, number>>;
-  order: Partial<Record<BreakpointKey, number>>;
-}
-
-// ============================================================================
-// Config Resolution
-// ============================================================================
-
-/**
- * Resolve a responsive configuration by applying defaults.
- *
- * @param config - SpecResponsiveConfig from the spec
- * @returns Fully resolved responsive configuration
- */
-export function resolveResponsiveConfig(config: SpecResponsiveConfig): ResolvedResponsiveConfig {
-  return {
-    breakpoint: config.breakpoint as BreakpointKey | undefined,
-    hiddenOn: (config.hiddenOn ?? []) as BreakpointKey[],
-    columns: (config.columns ?? {}) as Partial<Record<BreakpointKey, number>>,
-    order: (config.order ?? {}) as Partial<Record<BreakpointKey, number>>,
-  };
-}
-
-// ============================================================================
-// Visibility Classes
-// ============================================================================
-
-/**
- * Generate Tailwind CSS classes for responsive visibility.
- *
- * If `breakpoint` is set, the element is hidden below that breakpoint
- * (e.g. breakpoint "md" → `['hidden', 'md:block']`).
- *
- * If `hiddenOn` contains breakpoints, the element is hidden at those
- * specific sizes (e.g. hiddenOn: ["sm", "lg"] → `['sm:hidden', 'md:block', 'lg:hidden', 'xl:block']`).
- *
- * @param config - SpecResponsiveConfig from the spec
- * @returns Array of Tailwind CSS class strings
- */
-export function getVisibilityClasses(config: SpecResponsiveConfig): string[] {
-  const classes: string[] = [];
-
-  // Minimum breakpoint visibility
-  if (config.breakpoint) {
-    const bp = config.breakpoint as BreakpointKey;
-    if (bp !== 'xs') {
-      classes.push('hidden');
-      classes.push(`${bp}:block`);
-    }
-  }
-
-  // Per-breakpoint hidden overrides
-  const hiddenOn = (config.hiddenOn ?? []) as BreakpointKey[];
-  if (hiddenOn.length > 0) {
-    for (let i = 0; i < BREAKPOINT_ORDER.length; i++) {
-      const bp = BREAKPOINT_ORDER[i];
-      const isHidden = hiddenOn.includes(bp);
-      const prevHidden = i > 0 ? hiddenOn.includes(BREAKPOINT_ORDER[i - 1]) : false;
-
-      if (isHidden && !prevHidden) {
-        classes.push(bp === 'xs' ? 'hidden' : `${bp}:hidden`);
-      } else if (!isHidden && prevHidden) {
-        classes.push(bp === 'xs' ? 'block' : `${bp}:block`);
-      }
-    }
-  }
-
-  return classes;
-}
-
-// ============================================================================
-// Column Classes
-// ============================================================================
-
-/**
- * Generate Tailwind grid-cols classes for responsive column layouts.
- *
- * @param config - SpecResponsiveConfig from the spec
- * @returns Array of Tailwind CSS grid column class strings
- */
-export function getColumnClasses(config: SpecResponsiveConfig): string[] {
-  const classes: string[] = [];
-  const columns = (config.columns ?? {}) as Partial<Record<BreakpointKey, number>>;
-
-  for (const bp of BREAKPOINT_ORDER) {
-    const cols = columns[bp];
-    if (cols == null) continue;
-    const prefix = bp === 'xs' ? '' : `${bp}:`;
-    classes.push(`${prefix}grid-cols-${cols}`);
-  }
-
-  return classes;
-}
-
-// ============================================================================
-// Order Classes
-// ============================================================================
-
-/**
- * Generate Tailwind order utility classes for responsive ordering.
- *
- * @param config - SpecResponsiveConfig from the spec
- * @returns Array of Tailwind CSS order class strings
- */
-export function getOrderClasses(config: SpecResponsiveConfig): string[] {
-  const classes: string[] = [];
-  const order = (config.order ?? {}) as Partial<Record<BreakpointKey, number>>;
-
-  for (const bp of BREAKPOINT_ORDER) {
-    const ord = order[bp];
-    if (ord == null) continue;
-    const prefix = bp === 'xs' ? '' : `${bp}:`;
-    classes.push(`${prefix}order-${ord}`);
-  }
-
-  return classes;
-}
-
-// ============================================================================
-// Runtime Width Check
-// ============================================================================
-
-/**
- * Determine whether a component should be hidden at a given viewport width.
- *
- * Checks both the minimum `breakpoint` threshold and the `hiddenOn` list.
- *
- * @param config - SpecResponsiveConfig from the spec
- * @param width - Current viewport width in pixels
- * @returns `true` if the component should be hidden at the given width
- */
-export function shouldHideAtBreakpoint(config: SpecResponsiveConfig, width: number): boolean {
-  // Check minimum breakpoint
-  if (config.breakpoint) {
-    const minWidth = BREAKPOINT_VALUES[config.breakpoint as BreakpointKey];
-    if (minWidth !== undefined && width < minWidth) {
-      return true;
-    }
-  }
-
-  // Check hiddenOn list
-  const hiddenOn = (config.hiddenOn ?? []) as BreakpointKey[];
-  if (hiddenOn.length > 0) {
-    const currentBp = getCurrentBreakpoint(width);
-    return hiddenOn.includes(currentBp);
-  }
-
-  return false;
-}
-
-/**
- * Determine the current breakpoint name for a given width.
- */
-function getCurrentBreakpoint(width: number): BreakpointKey {
-  for (let i = BREAKPOINT_ORDER.length - 1; i >= 0; i--) {
-    if (width >= BREAKPOINT_VALUES[BREAKPOINT_ORDER[i]]) {
-      return BREAKPOINT_ORDER[i];
-    }
-  }
-  return 'xs';
-}