@mt-gloss/ui 0.0.2

package/lib/hooks/useArrowNavigation.d.ts

@@ -0,0 +1,106 @@
+export interface UseArrowNavigationOptions<T> {
+    /**
+     * Array of items to navigate through
+     */
+    items: T[];
+    /**
+     * Current active index
+     */
+    activeIndex?: number;
+    /**
+     * Callback when active index changes
+     */
+    onActiveIndexChange?: (index: number) => void;
+    /**
+     * Whether to wrap around when reaching ends
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Orientation of the list
+     * @default 'vertical'
+     */
+    orientation?: 'vertical' | 'horizontal' | 'both';
+    /**
+     * Whether navigation is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Filter function to skip disabled items
+     */
+    isItemDisabled?: (item: T, index: number) => boolean;
+    /**
+     * Callback when Enter/Space is pressed on active item
+     */
+    onSelect?: (item: T, index: number) => void;
+    /**
+     * Callback when Escape is pressed
+     */
+    onEscape?: () => void;
+}
+export interface UseArrowNavigationReturn {
+    /**
+     * Current focused index
+     */
+    focusedIndex: number;
+    /**
+     * Set focused index manually
+     */
+    setFocusedIndex: (index: number) => void;
+    /**
+     * Key down handler to attach to container
+     */
+    handleKeyDown: (event: React.KeyboardEvent) => void;
+    /**
+     * Move focus to first item
+     */
+    focusFirst: () => void;
+    /**
+     * Move focus to last item
+     */
+    focusLast: () => void;
+    /**
+     * Move focus to next item
+     */
+    focusNext: () => void;
+    /**
+     * Move focus to previous item
+     */
+    focusPrevious: () => void;
+    /**
+     * Reset focus to -1 (no item focused)
+     */
+    resetFocus: () => void;
+}
+/**
+ * Hook for keyboard navigation with arrow keys
+ *
+ * @example
+ * ```tsx
+ * function MenuList({ items, onSelect }) {
+ *   const {
+ *     focusedIndex,
+ *     handleKeyDown,
+ *   } = useArrowNavigation({
+ *     items,
+ *     onSelect: (item) => onSelect(item),
+ *   });
+ *
+ *   return (
+ *     <ul role="menu" onKeyDown={handleKeyDown}>
+ *       {items.map((item, index) => (
+ *         <li
+ *           key={item.id}
+ *           role="menuitem"
+ *           data-focused={index === focusedIndex}
+ *         >
+ *           {item.label}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function useArrowNavigation<T>(options: UseArrowNavigationOptions<T>): UseArrowNavigationReturn;

package/lib/hooks/useFocusReturn.d.ts

@@ -0,0 +1,26 @@
+export interface UseFocusReturnOptions {
+    /**
+     * Whether focus return is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Custom element to return focus to
+     */
+    returnTo?: HTMLElement | null;
+}
+/**
+ * Hook to return focus to the previously focused element when component unmounts
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, children }) {
+ *   useFocusReturn({ enabled: isOpen });
+ *
+ *   if (!isOpen) return null;
+ *
+ *   return <div>{children}</div>;
+ * }
+ * ```
+ */
+export declare function useFocusReturn(options?: UseFocusReturnOptions): import('react').RefObject<Element | null>;

package/lib/hooks/useFocusTrap.d.ts

@@ -0,0 +1,50 @@
+export interface UseFocusTrapOptions {
+    /**
+     * Whether the focus trap is active
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to auto-focus the first focusable element
+     * @default true
+     */
+    autoFocus?: boolean;
+    /**
+     * Whether to return focus to the previously focused element on deactivation
+     * @default true
+     */
+    returnFocusOnDeactivate?: boolean;
+    /**
+     * Initial element to focus (selector or element)
+     */
+    initialFocus?: string | HTMLElement;
+    /**
+     * Allow focus outside the trap (for click outside handlers)
+     * @default false
+     */
+    allowOutsideClick?: boolean;
+    /**
+     * Callback when escape is pressed
+     */
+    onEscape?: () => void;
+}
+/**
+ * Hook to trap focus within a container element
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose, children }) {
+ *   const trapRef = useFocusTrap<HTMLDivElement>({
+ *     enabled: isOpen,
+ *     onEscape: onClose,
+ *   });
+ *
+ *   return (
+ *     <div ref={trapRef} role="dialog">
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFocusTrap<T extends HTMLElement = HTMLElement>(options?: UseFocusTrapOptions): import('react').RefObject<T | null>;

package/lib/patterns/feedback/DestructiveModal.d.ts

@@ -0,0 +1,31 @@
+import { PatternMetadata } from '../types';
+export interface DestructiveModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Called when the modal should close */
+    onClose: () => void;
+    /** Called when the destructive action is confirmed */
+    onConfirm: () => void | Promise<void>;
+    /** Title of the modal */
+    title?: string;
+    /** Description/warning message */
+    description?: string;
+    /** Text for the confirm button */
+    confirmLabel?: string;
+    /** Text for the cancel button */
+    cancelLabel?: string;
+    /** Require user to type confirmation text */
+    requireConfirmation?: boolean;
+    /** Text the user must type to confirm (e.g., "DELETE") */
+    confirmationText?: string;
+    /** Placeholder for the confirmation input */
+    confirmationPlaceholder?: string;
+    /** Loading state for the confirm button */
+    isLoading?: boolean;
+    /** The name of the resource being deleted (shown in description) */
+    resourceName?: string;
+    /** Icon to display (default: alert-triangle) */
+    icon?: string;
+}
+export declare const metadata: PatternMetadata;
+export default function DestructiveModal({ isOpen, onClose, onConfirm, title, description, confirmLabel, cancelLabel, requireConfirmation, confirmationText, confirmationPlaceholder, isLoading, resourceName, icon, }: DestructiveModalProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/patterns/feedback/index.d.ts

@@ -0,0 +1 @@
+export { default as DestructiveModal, metadata as destructiveModalMetadata, type DestructiveModalProps, } from './DestructiveModal';

package/lib/patterns/forms/AddressGroup.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { PatternMetadata } from '../types';
+export declare const addressSchema: z.ZodObject<{
+    street: z.ZodString;
+    street2: z.ZodOptional<z.ZodString>;
+    city: z.ZodString;
+    state: z.ZodString;
+    zip: z.ZodString;
+    country: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type AddressFormValues = z.infer<typeof addressSchema>;
+export interface AddressGroupProps {
+    /** Legend/title for the fieldset */
+    legend?: string;
+    /** Use compact layout (2 columns where possible) */
+    compact?: boolean;
+    /** Show address line 2 field */
+    showStreet2?: boolean;
+    /** Show country field */
+    showCountry?: boolean;
+    /** Default country value */
+    defaultCountry?: string;
+    /** Disable all fields */
+    disabled?: boolean;
+    /** Make all fields required */
+    required?: boolean;
+    /** Default form values */
+    defaultValues?: Partial<AddressFormValues>;
+    /** Called when any field changes */
+    onChange?: (values: Partial<AddressFormValues>) => void;
+    /** Called when a field loses focus */
+    onBlur?: (field: keyof AddressFormValues) => void;
+    /** External validation errors */
+    errors?: Partial<Record<keyof AddressFormValues, string>>;
+}
+export declare const metadata: PatternMetadata;
+export default function AddressGroup({ legend, compact, showStreet2, showCountry, defaultCountry, disabled, required, defaultValues, onChange, onBlur, errors: externalErrors, }: AddressGroupProps): import("react/jsx-runtime").JSX.Element;

package/lib/patterns/forms/CreditCardForm.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { PatternMetadata } from '../types';
+export declare const creditCardSchema: z.ZodObject<{
+    cardNumber: z.ZodString;
+    expiryDate: z.ZodString;
+    cvv: z.ZodString;
+    cardholderName: z.ZodString;
+}, z.core.$strip>;
+export type CreditCardFormValues = z.infer<typeof creditCardSchema>;
+export interface CreditCardFormProps {
+    /** Title displayed at the top of the form */
+    title?: string;
+    /** Subtitle/description below the title */
+    subtitle?: string;
+    /** Text for the submit button */
+    submitLabel?: string;
+    /** Amount to display on submit button (e.g., "$99.00") */
+    amount?: string;
+    /** Show cancel button */
+    showCancel?: boolean;
+    /** Cancel button label */
+    cancelLabel?: string;
+    /** Loading state for the submit button */
+    isLoading?: boolean;
+    /** Show async validation indicator on card number */
+    isValidating?: boolean;
+    /** Disable the entire form */
+    disabled?: boolean;
+    /** Show lock icon on submit button */
+    showSecureIcon?: boolean;
+    /** Default form values */
+    defaultValues?: Partial<CreditCardFormValues>;
+    /** Called when form is submitted with valid data */
+    onSubmit?: (values: CreditCardFormValues) => void | Promise<void>;
+    /** Called when cancel button is clicked */
+    onCancel?: () => void;
+    /** Called when card number changes (for async BIN validation) */
+    onCardNumberChange?: (cardNumber: string) => void;
+}
+export declare const metadata: PatternMetadata;
+export default function CreditCardForm({ title, subtitle, submitLabel, amount, showCancel, cancelLabel, isLoading, isValidating, disabled, showSecureIcon, defaultValues, onSubmit, onCancel, onCardNumberChange, }: CreditCardFormProps): import("react/jsx-runtime").JSX.Element;

package/lib/patterns/forms/LoginForm.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { PatternMetadata } from '../types';
+export declare const loginSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    rememberMe: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LoginFormValues = z.infer<typeof loginSchema>;
+export interface LoginFormProps {
+    /** Title displayed at the top of the form */
+    title?: string;
+    /** Subtitle/description below the title */
+    subtitle?: string;
+    /** Text for the submit button */
+    submitLabel?: string;
+    /** Show "Remember me" checkbox */
+    showRememberMe?: boolean;
+    /** Show "Forgot password" link */
+    showForgotPassword?: boolean;
+    /** URL for forgot password link */
+    forgotPasswordUrl?: string;
+    /** Show registration link */
+    showRegisterLink?: boolean;
+    /** Registration link URL */
+    registerUrl?: string;
+    /** Loading state for the submit button */
+    isLoading?: boolean;
+    /** Disable the entire form */
+    disabled?: boolean;
+    /** Default form values */
+    defaultValues?: Partial<LoginFormValues>;
+    /** Called when form is submitted with valid data */
+    onSubmit?: (values: LoginFormValues) => void | Promise<void>;
+    /** Called when forgot password link is clicked */
+    onForgotPassword?: () => void;
+}
+export declare const metadata: PatternMetadata;
+export default function LoginForm({ title, subtitle, submitLabel, showRememberMe, showForgotPassword, forgotPasswordUrl, showRegisterLink, registerUrl, isLoading, disabled, defaultValues, onSubmit, onForgotPassword, }: LoginFormProps): import("react/jsx-runtime").JSX.Element;

package/lib/patterns/forms/index.d.ts

@@ -0,0 +1,3 @@
+export { default as LoginForm, metadata as loginFormMetadata, loginSchema, type LoginFormProps, } from './LoginForm';
+export { default as AddressGroup, metadata as addressGroupMetadata, addressSchema, type AddressGroupProps, } from './AddressGroup';
+export { default as CreditCardForm, metadata as creditCardFormMetadata, creditCardSchema, type CreditCardFormProps, } from './CreditCardForm';

package/lib/patterns/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Gloss UI Patterns
+ *
+ * Composite, pre-configured component groupings for common use cases.
+ * Each pattern exports:
+ * - Default: The React component
+ * - metadata: PatternMetadata for database sync
+ * - schema (optional): Zod validation schema
+ */
+export type { PatternMetadata, PatternPropDefinition, PatternCategory, PatternRecord, } from './types';
+export { default as LoginForm, metadata as loginFormMetadata, loginSchema, type LoginFormProps, } from './forms/LoginForm';
+export { default as AddressGroup, metadata as addressGroupMetadata, addressSchema, type AddressGroupProps, } from './forms/AddressGroup';
+export { default as CreditCardForm, metadata as creditCardFormMetadata, creditCardSchema, type CreditCardFormProps, } from './forms/CreditCardForm';
+export { default as DestructiveModal, metadata as destructiveModalMetadata, type DestructiveModalProps, } from './feedback/DestructiveModal';

package/lib/patterns/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pattern System Types
+ *
+ * These types define the contract for pattern components and their metadata.
+ * Patterns are composite, pre-configured groupings of primitive components
+ * designed to be consumed by production developers.
+ */
+/**
+ * Defines a single prop that can be configured in the Pattern Studio
+ */
+export interface PatternPropDefinition {
+    /** The prop name (must match the component prop) */
+    name: string;
+    /** The prop type for form generation */
+    type: 'string' | 'boolean' | 'number' | 'select' | 'object';
+    /** Default value for this prop */
+    default?: unknown;
+    /** Whether this prop is required */
+    required?: boolean;
+    /** Options for 'select' type props */
+    options?: string[];
+    /** Human-readable description for the Pattern Studio */
+    description?: string;
+}
+/**
+ * Pattern categories for organization and filtering
+ */
+export type PatternCategory = 'forms' | 'overlays' | 'feedback' | 'navigation' | 'data-display';
+/**
+ * Metadata for a pattern component, used for:
+ * - Database sync (Neon)
+ * - Pattern Studio props generation
+ * - Documentation catalog
+ */
+export interface PatternMetadata {
+    /** URL-friendly unique identifier (e.g., 'login-form', 'address-group') */
+    slug: string;
+    /** Human-readable name (e.g., 'Login Form', 'Address Group') */
+    displayName: string;
+    /** Brief description of the pattern's purpose */
+    description: string;
+    /** Category for filtering in the catalog */
+    category: PatternCategory;
+    /** Tags for search and filtering */
+    tags: string[];
+    /** Props that can be configured in the Pattern Studio */
+    propsDefinition: PatternPropDefinition[];
+    /** Optional version string */
+    version?: string;
+}
+/**
+ * Database row type for patterns table
+ */
+export interface PatternRecord {
+    id: number;
+    slug: string;
+    name: string;
+    description: string | null;
+    category: string;
+    tags: string[];
+    props_definition: PatternPropDefinition[];
+    updated_at: string;
+}

package/lib/types/icon.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+/**
+ * Icon value can be either a string (icon name from sprite) or a ReactNode
+ */
+export type IconValue = string | React.ReactNode;
+/**
+ * Common icon slot props shared across Button, Input, and Select components
+ */
+export interface IconSlotProps {
+    /**
+     * Icon displayed on the left side of the component
+     * Can be an icon name (string) or a custom React element
+     */
+    leftIcon?: IconValue;
+    /**
+     * Icon displayed on the right side of the component
+     * Can be an icon name (string) or a custom React element
+     */
+    rightIcon?: IconValue;
+    /**
+     * Vertical alignment of icons relative to content
+     * - 'center': Icons are vertically centered (default)
+     * - 'top': Icons align to the top (useful for multi-line content)
+     * @default 'center'
+     */
+    iconAlign?: 'top' | 'center';
+}

package/lib/utils/animations.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Animation utilities and presets for Gloss UI components
+ */
+/**
+ * Standard animation durations
+ */
+export declare const durations: {
+    readonly instant: 0;
+    readonly fast: 100;
+    readonly normal: 200;
+    readonly slow: 300;
+    readonly slower: 400;
+};
+export type AnimationDuration = keyof typeof durations;
+/**
+ * Standard easing functions
+ */
+export declare const easings: {
+    readonly linear: "linear";
+    readonly easeIn: "cubic-bezier(0.4, 0, 1, 1)";
+    readonly easeOut: "cubic-bezier(0, 0, 0.2, 1)";
+    readonly easeInOut: "cubic-bezier(0.4, 0, 0.2, 1)";
+    readonly spring: "cubic-bezier(0.175, 0.885, 0.32, 1.275)";
+};
+export type AnimationEasing = keyof typeof easings;
+/**
+ * Animation preset configurations
+ */
+export interface AnimationPreset {
+    enter: {
+        from: React.CSSProperties;
+        to: React.CSSProperties;
+    };
+    exit: {
+        from: React.CSSProperties;
+        to: React.CSSProperties;
+    };
+    duration: number;
+    easing: string;
+}
+/**
+ * Common animation presets
+ */
+export declare const presets: Record<string, AnimationPreset>;
+export type AnimationPresetName = keyof typeof presets;
+/**
+ * Get CSS transition string from animation config
+ */
+export declare function getTransitionStyle(properties: string[], duration?: number, easing?: string): string;
+/**
+ * Interpolate between two values based on progress (0-1)
+ */
+export declare function interpolate(from: number, to: number, progress: number): number;
+/**
+ * Parse a CSS value like "8px" to a number
+ */
+export declare function parseNumericValue(value: string): {
+    value: number;
+    unit: string;
+};

package/lib/utils/renderIcon.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+import { IconValue } from '../types/icon';
+type IconSize = 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Renders an icon from either a string (icon name) or a ReactNode
+ *
+ * @param icon - Icon name string or ReactNode
+ * @param size - Icon size (only used when icon is a string)
+ * @returns ReactNode to render
+ *
+ * @example
+ * ```tsx
+ * // String icon name - renders Icon component
+ * renderIcon('check', 'sm')
+ *
+ * // ReactNode - rendered as-is
+ * renderIcon(<CustomIcon />)
+ * ```
+ */
+export declare function renderIcon(icon: IconValue | undefined, size?: IconSize): React.ReactNode;
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@mt-gloss/ui",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    },
+    "./styles.css": "./index.css"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.css",
+    "lib/**/*.d.ts",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@mui/material": "^6.0.0 || ^7.0.0",
+    "@mui/icons-material": "^6.0.0 || ^7.0.0",
+    "@emotion/react": "^11.0.0",
+    "@emotion/styled": "^11.0.0",
+    "date-fns": "^3.0.0 || ^4.0.0",
+    "@mt-gloss/utils": ">=0.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@mui/material": { "optional": false },
+    "@mui/icons-material": { "optional": false },
+    "@emotion/react": { "optional": false },
+    "@emotion/styled": { "optional": false },
+    "date-fns": { "optional": false },
+    "@dnd-kit/core": { "optional": true },
+    "@dnd-kit/sortable": { "optional": true },
+    "@dnd-kit/modifiers": { "optional": true },
+    "@dnd-kit/utilities": { "optional": true },
+    "@mui/x-data-grid-pro": { "optional": true },
+    "@mui/x-date-pickers-pro": { "optional": true }
+  },
+  "optionalDependencies": {
+    "@dnd-kit/core": "^6.0.0",
+    "@dnd-kit/sortable": "^8.0.0 || ^9.0.0 || ^10.0.0",
+    "@dnd-kit/modifiers": "^7.0.0 || ^8.0.0 || ^9.0.0",
+    "@dnd-kit/utilities": "^3.0.0",
+    "@mui/x-data-grid-pro": "^7.0.0 || ^8.0.0",
+    "@mui/x-date-pickers-pro": "^7.0.0 || ^8.0.0"
+  }
+}