brix-runtime-sdk-api-web 1.0.0

package/src/types/ui/input.ts

@@ -0,0 +1,225 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file Input Component Type Definitions
+ * @description Defines types for the Input component in the UI adapter system
+ * @module @brix/runtime-sdk-api-web/types/ui/input
+ * @version 3.2.0
+ */
+
+import type { ChangeEvent, KeyboardEvent, FocusEvent, CSSProperties } from 'react';
+import type { ComponentSize } from './common';
+
+/**
+ * Input Field Type
+ *
+ * HTML input type attribute values supported by the Input component.
+ */
+export type InputType = 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search';
+
+/**
+ * Input Component Props
+ *
+ * UI library agnostic input field properties. Supports all standard
+ * text input use cases with validation and accessibility features.
+ *
+ * @example
+ * ```tsx
+ * <Input
+ *   label="Email"
+ *   type="email"
+ *   placeholder="Enter your email"
+ *   value={email}
+ *   onChange={(e) => setEmail(e.target.value)}
+ *   error={!isValidEmail}
+ *   helperText={!isValidEmail ? 'Invalid email format' : ''}
+ * />
+ * ```
+ */
+export interface InputProps {
+  /**
+   * Input Field Type
+   *
+   * Determines the input behavior and keyboard on mobile devices.
+   * @default 'text'
+   */
+  type?: InputType;
+
+  /**
+   * Current Value
+   *
+   * The controlled value of the input field.
+   */
+  value?: string;
+
+  /**
+   * Default Value
+   *
+   * The initial value for uncontrolled input usage.
+   */
+  defaultValue?: string;
+
+  /**
+   * Placeholder Text
+   *
+   * Hint text displayed when the input is empty.
+   */
+  placeholder?: string;
+
+  /**
+   * Field Label
+   *
+   * Accessible label displayed above or beside the input.
+   */
+  label?: string;
+
+  /**
+   * Helper Text
+   *
+   * Descriptive text displayed below the input for guidance.
+   */
+  helperText?: string;
+
+  /**
+   * Error State
+   *
+   * When true, displays the input in an error state with visual feedback.
+   * @default false
+   */
+  error?: boolean;
+
+  /**
+   * Disabled State
+   *
+   * When true, the input is non-interactive and visually dimmed.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Read-Only State
+   *
+   * When true, the input value can be selected but not modified.
+   * @default false
+   */
+  readOnly?: boolean;
+
+  /**
+   * Required Field Indicator
+   *
+   * When true, displays a required field indicator.
+   * @default false
+   */
+  required?: boolean;
+
+  /**
+   * Input Size
+   *
+   * Controls the input dimensions and font size.
+   * @default 'medium'
+   */
+  size?: ComponentSize;
+
+  /**
+   * Full Width Mode
+   *
+   * When true, the input expands to fill its container width.
+   * @default false
+   */
+  fullWidth?: boolean;
+
+  /**
+   * Start Adornment Icon
+   *
+   * Icon name displayed at the start of the input.
+   */
+  startAdornment?: string;
+
+  /**
+   * End Adornment Icon
+   *
+   * Icon name displayed at the end of the input.
+   * Commonly used for clear button or visibility toggle.
+   */
+  endAdornment?: string;
+
+  /**
+   * Maximum Character Length
+   *
+   * Maximum number of characters allowed in the input.
+   */
+  maxLength?: number;
+
+  /**
+   * HTML Name Attribute
+   *
+   * Form field name for form submission.
+   */
+  name?: string;
+
+  /**
+   * Auto Focus
+   *
+   * When true, the input receives focus on mount.
+   * @default false
+   */
+  autoFocus?: boolean;
+
+  /**
+   * Auto Complete Hint
+   *
+   * Browser autocomplete hint for the input field.
+   */
+  autoComplete?: string;
+
+  /**
+   * Change Event Handler
+   *
+   * Callback fired when the input value changes.
+   */
+  onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+
+  /**
+   * Focus Event Handler
+   *
+   * Callback fired when the input receives focus.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+
+  /**
+   * Blur Event Handler
+   *
+   * Callback fired when the input loses focus.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+
+  /**
+   * Key Down Event Handler
+   *
+   * Callback fired on key down events.
+   */
+  onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+
+  /**
+   * Custom Inline Styles
+   */
+  style?: CSSProperties;
+
+  /**
+   * Custom CSS Class Name
+   */
+  className?: string;
+}

package/src/types/ui/menu.ts

@@ -0,0 +1,237 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file Menu Component Type Definitions
+ * @description Defines types for the Menu and MenuItem components in the UI adapter system
+ * @module @brix/runtime-sdk-api-web/types/ui/menu
+ * @version 3.2.0
+ *
+ * [Architectural Note]
+ * These are ATOMIC navigation components for Shell layer assembly.
+ * Sidebar and Header are assembled at Shell layer using these components.
+ */
+
+import type { ReactNode, MouseEvent, CSSProperties } from 'react';
+
+/**
+ * Menu Item Definition
+ *
+ * Represents a navigation item in the menu hierarchy.
+ * Used by both the Menu component and Shell layout components.
+ */
+export interface MenuItem {
+  /**
+   * Unique Item Key
+   *
+   * Unique identifier for the menu item. Used for selection tracking.
+   */
+  key: string;
+
+  /**
+   * Display Label
+   *
+   * The text displayed for this menu item.
+   */
+  label: ReactNode;
+
+  /**
+   * Icon Name
+   *
+   * Optional icon displayed before the label.
+   */
+  icon?: string;
+
+  /**
+   * Navigation Path
+   *
+   * The URL path this item navigates to.
+   */
+  path?: string;
+
+  /**
+   * Child Items
+   *
+   * Nested submenu items.
+   */
+  children?: MenuItem[];
+
+  /**
+   * Hidden State
+   *
+   * When true, the item is not rendered.
+   */
+  hidden?: boolean;
+
+  /**
+   * Sort Order
+   *
+   * Numeric weight for sorting. Lower values appear first.
+   */
+  order?: number;
+
+  /**
+   * Disabled State
+   *
+   * When true, the item is non-interactive.
+   */
+  disabled?: boolean;
+
+  /**
+   * Badge Count
+   *
+   * Optional notification count displayed on the item.
+   */
+  badge?: number;
+}
+
+/**
+ * Menu Component Props
+ *
+ * Atomic navigation menu component. This is a presentation component
+ * used by Shell layer to assemble layout components like Sidebar.
+ *
+ * **Architectural Note:** This is an atomic component.
+ * Sidebar and Header are assembled at Shell layer using this component.
+ *
+ * @example
+ * ```tsx
+ * <Menu
+ *   items={menuItems}
+ *   selectedKey={currentPath}
+ *   onSelect={(key, item) => navigate(item.path)}
+ *   collapsed={sidebarCollapsed}
+ * />
+ * ```
+ */
+export interface MenuProps {
+  /**
+   * Menu Items
+   *
+   * Array of menu items to render.
+   */
+  items: MenuItem[];
+
+  /**
+   * Selected Item Key
+   *
+   * Key of the currently selected item for highlight.
+   */
+  selectedKey?: string;
+
+  /**
+   * Expanded Keys
+   *
+   * Keys of expanded submenu items.
+   */
+  expandedKeys?: string[];
+
+  /**
+   * Default Expanded Keys
+   *
+   * Initially expanded submenu keys for uncontrolled usage.
+   */
+  defaultExpandedKeys?: string[];
+
+  /**
+   * Selection Handler
+   *
+   * Callback fired when a menu item is selected.
+   */
+  onSelect?: (key: string, item: MenuItem) => void;
+
+  /**
+   * Expand Handler
+   *
+   * Callback fired when submenu expand state changes.
+   */
+  onExpand?: (expandedKeys: string[]) => void;
+
+  /**
+   * Collapsed Mode
+   *
+   * When true, displays the menu in collapsed icon-only mode.
+   * @default false
+   */
+  collapsed?: boolean;
+
+  /**
+   * Inline Mode
+   *
+   * When true, submenus expand inline. When false, submenus popup.
+   * @default true
+   */
+  inlineMode?: boolean;
+
+  /**
+   * Custom Inline Styles
+   */
+  style?: CSSProperties;
+
+  /**
+   * Custom CSS Class Name
+   */
+  className?: string;
+}
+
+/**
+ * Menu Item Component Props
+ *
+ * Individual menu item component props. Used for custom menu item rendering.
+ */
+export interface MenuItemProps {
+  /**
+   * Item Data
+   *
+   * The menu item data object.
+   */
+  item: MenuItem;
+
+  /**
+   * Selected State
+   *
+   * Whether this item is currently selected.
+   */
+  selected?: boolean;
+
+  /**
+   * Depth Level
+   *
+   * Nesting depth for indentation (0 = root level).
+   */
+  depth?: number;
+
+  /**
+   * Collapsed Mode
+   *
+   * Whether the parent menu is in collapsed mode.
+   */
+  collapsed?: boolean;
+
+  /**
+   * Click Handler
+   */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+
+  /**
+   * Custom Inline Styles
+   */
+  style?: CSSProperties;
+
+  /**
+   * Custom CSS Class Name
+   */
+  className?: string;
+}

package/src/types/ui/message.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file Message API Type Definitions
+ * @description Defines types for the Toast/Snackbar Message API in the UI adapter system
+ * @module @brix/runtime-sdk-api-web/types/ui/message
+ * @version 3.2.0
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * Message Type Variants
+ */
+export type MessageType = 'success' | 'error' | 'warning' | 'info' | 'loading';
+
+/**
+ * Message Configuration Options
+ */
+export interface MessageOptions {
+  /**
+   * Message Content
+   */
+  content: ReactNode;
+
+  /**
+   * Display Duration (ms)
+   *
+   * Duration before auto-dismiss. 0 means manual dismiss only.
+   * @default 3000
+   */
+  duration?: number;
+
+  /**
+   * Closable
+   *
+   * When true, displays a close button.
+   * @default false
+   */
+  closable?: boolean;
+
+  /**
+   * Unique Key
+   *
+   * Unique key for updating or closing specific messages.
+   */
+  key?: string;
+
+  /**
+   * Close Callback
+   *
+   * Callback fired when the message is closed.
+   */
+  onClose?: () => void;
+}
+
+/**
+ * Message Destroy Function
+ *
+ * Function returned by message calls to manually dismiss the message.
+ */
+export type MessageDestroy = () => void;
+
+/**
+ * Message API Interface
+ *
+ * Imperative API for displaying toast/snackbar messages.
+ * This is a stateless API - implementations manage message state internally.
+ *
+ * @example
+ * ```tsx
+ * // Using the message API from UIAdapter
+ * const { message } = useUI();
+ *
+ * message.success({ content: 'Saved successfully!' });
+ * message.error({ content: 'Operation failed', duration: 5000 });
+ *
+ * // With loading state
+ * const destroy = message.loading({ content: 'Processing...' });
+ * await doAsyncOperation();
+ * destroy();
+ * message.success({ content: 'Done!' });
+ * ```
+ */
+export interface MessageAPI {
+  /**
+   * Success Message
+   */
+  success: (options: MessageOptions | string) => MessageDestroy;
+
+  /**
+   * Error Message
+   */
+  error: (options: MessageOptions | string) => MessageDestroy;
+
+  /**
+   * Warning Message
+   */
+  warning: (options: MessageOptions | string) => MessageDestroy;
+
+  /**
+   * Info Message
+   */
+  info: (options: MessageOptions | string) => MessageDestroy;
+
+  /**
+   * Loading Message
+   */
+  loading: (options: MessageOptions | string) => MessageDestroy;
+
+  /**
+   * Destroy Specific Message
+   *
+   * Destroys a message by its key.
+   */
+  destroy: (key?: string) => void;
+
+  /**
+   * Destroy All Messages
+   */
+  destroyAll: () => void;
+}