@object-ui/core 3.0.2 → 3.1.0

package/dist/protocols/DndProtocol.js

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// 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) {
+    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) {
+    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) {
+    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) {
+    const styles = {
+        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/dist/protocols/KeyboardProtocol.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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, FocusTrapConfig } from '@object-ui/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;
+}
+/**
+ * Resolve a keyboard navigation configuration by applying spec defaults.
+ *
+ * @param config - KeyboardNavigationConfig from the spec
+ * @returns Fully resolved keyboard navigation configuration
+ */
+export declare function resolveKeyboardConfig(config: KeyboardNavigationConfig): ResolvedKeyboardConfig;
+/**
+ * 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 declare function parseShortcutKey(shortcut: string): ParsedShortcut;
+/**
+ * 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 declare function matchesShortcut(event: KeyboardEventLike, shortcut: string): boolean;
+/**
+ * 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 declare function createFocusTrapConfig(config: FocusTrapConfig): ResolvedFocusTrapConfig;

package/dist/protocols/KeyboardProtocol.js

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// 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) {
+    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) {
+    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) {
+    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, shortcut) {
+    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) {
+    return {
+        enabled: config.enabled ?? false,
+        initialFocus: config.initialFocus,
+        returnFocus: config.returnFocus ?? true,
+        escapeDeactivates: config.escapeDeactivates ?? true,
+    };
+}

package/dist/protocols/NotificationProtocol.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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, NotificationConfig, NotificationPosition } from '@object-ui/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';
+}
+/**
+ * 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 declare function mapSeverityToVariant(severity: string): string;
+/**
+ * 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 declare function mapPosition(position: string): string;
+/**
+ * Resolve a notification configuration by applying spec defaults.
+ *
+ * @param config - NotificationConfig from the spec
+ * @returns Fully resolved notification configuration
+ */
+export declare function resolveNotificationConfig(config: NotificationConfig): ResolvedNotificationConfig;
+/**
+ * Convert a spec Notification to a toast-compatible object.
+ *
+ * @param notification - Spec Notification
+ * @returns Toast-compatible notification with title, description, variant, etc.
+ */
+export declare function specNotificationToToast(notification: SpecNotification): ToastNotification;

package/dist/protocols/NotificationProtocol.js

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// Severity → Variant Mapping
+// ============================================================================
+const SEVERITY_TO_VARIANT = {
+    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) {
+    return SEVERITY_TO_VARIANT[severity] ?? 'default';
+}
+// ============================================================================
+// Position Mapping
+// ============================================================================
+const POSITION_MAP = {
+    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) {
+    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) {
+    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) {
+    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) {
+    const actions = (notification.actions ?? []).map((a) => ({
+        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,
+    };
+}

package/dist/protocols/ResponsiveProtocol.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 name type matching Tailwind defaults. */
+export type BreakpointKey = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/** Breakpoint minimum pixel widths aligned with Tailwind CSS defaults. */
+export declare const BREAKPOINT_VALUES: Record<BreakpointKey, number>;
+/** Fully resolved responsive configuration. */
+export interface ResolvedResponsiveConfig {
+    breakpoint?: BreakpointKey;
+    hiddenOn: BreakpointKey[];
+    columns: Partial<Record<BreakpointKey, number>>;
+    order: Partial<Record<BreakpointKey, number>>;
+}
+/**
+ * Resolve a responsive configuration by applying defaults.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Fully resolved responsive configuration
+ */
+export declare function resolveResponsiveConfig(config: SpecResponsiveConfig): ResolvedResponsiveConfig;
+/**
+ * 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 declare function getVisibilityClasses(config: SpecResponsiveConfig): string[];
+/**
+ * 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 declare function getColumnClasses(config: SpecResponsiveConfig): string[];
+/**
+ * Generate Tailwind order utility classes for responsive ordering.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Array of Tailwind CSS order class strings
+ */
+export declare function getOrderClasses(config: SpecResponsiveConfig): string[];
+/**
+ * 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 declare function shouldHideAtBreakpoint(config: SpecResponsiveConfig, width: number): boolean;