@mt-gloss/ui 0.0.2

package/lib/Form.d.ts

@@ -0,0 +1,119 @@
+import { default as React } from 'react';
+export interface FormErrors {
+    [key: string]: string | undefined;
+}
+export interface FormTouched {
+    [key: string]: boolean;
+}
+export interface FormContextValue {
+    /**
+     * Form values
+     */
+    values: Record<string, unknown>;
+    /**
+     * Form errors
+     */
+    errors: FormErrors;
+    /**
+     * Touched fields
+     */
+    touched: FormTouched;
+    /**
+     * Whether form is submitting
+     */
+    isSubmitting: boolean;
+    /**
+     * Whether form is valid
+     */
+    isValid: boolean;
+    /**
+     * Set a field value
+     */
+    setFieldValue: (name: string, value: unknown) => void;
+    /**
+     * Set a field error
+     */
+    setFieldError: (name: string, error: string | undefined) => void;
+    /**
+     * Mark a field as touched
+     */
+    setFieldTouched: (name: string, touched?: boolean) => void;
+    /**
+     * Get field props for binding to input
+     */
+    getFieldProps: (name: string) => {
+        value: unknown;
+        onChange: (value: unknown) => void;
+        onBlur: () => void;
+        name: string;
+        error: string | undefined;
+        touched: boolean;
+    };
+}
+export declare function useFormContext(): FormContextValue;
+export interface FormProps<T extends Record<string, unknown>> {
+    /**
+     * Initial form values
+     */
+    initialValues: T;
+    /**
+     * Validation function
+     */
+    validate?: (values: T) => FormErrors | Promise<FormErrors>;
+    /**
+     * Submit handler
+     */
+    onSubmit: (values: T) => void | Promise<void>;
+    /**
+     * Validate on change
+     * @default true
+     */
+    validateOnChange?: boolean;
+    /**
+     * Validate on blur
+     * @default true
+     */
+    validateOnBlur?: boolean;
+    /**
+     * Form children (can be render prop)
+     */
+    children: React.ReactNode | ((context: FormContextValue) => React.ReactNode);
+    /**
+     * Additional class name
+     */
+    className?: string;
+    /**
+     * Prevent default form submission
+     * @default true
+     */
+    preventDefault?: boolean;
+}
+/**
+ * Form component with validation and state management
+ *
+ * @example
+ * ```tsx
+ * <Form
+ *   initialValues={{ email: '', password: '' }}
+ *   validate={(values) => {
+ *     const errors: FormErrors = {};
+ *     if (!values.email) errors.email = 'Required';
+ *     if (!values.password) errors.password = 'Required';
+ *     return errors;
+ *   }}
+ *   onSubmit={(values) => console.log(values)}
+ * >
+ *   <FormField name="email" label="Email">
+ *     <Input />
+ *   </FormField>
+ *   <FormField name="password" label="Password">
+ *     <Input type="password" />
+ *   </FormField>
+ *   <Button type="submit">Submit</Button>
+ * </Form>
+ * ```
+ */
+export declare function Form<T extends Record<string, unknown>>({ initialValues, validate, onSubmit, validateOnChange, validateOnBlur, children, className, preventDefault, }: FormProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Form {
+    var displayName: string;
+}

package/lib/FormField.d.ts

@@ -0,0 +1,69 @@
+import { default as React } from 'react';
+interface FormControlProps {
+    id?: string;
+    name?: string;
+    value?: unknown;
+    onChange?: (value: unknown) => void;
+    onBlur?: (event: React.FocusEvent) => void;
+    status?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
+    'aria-required'?: boolean;
+}
+export interface FormFieldProps {
+    /**
+     * Field name (must match a key in form values)
+     */
+    name: string;
+    /**
+     * Field label
+     */
+    label?: React.ReactNode;
+    /**
+     * Helper text shown below the field
+     */
+    helperText?: React.ReactNode;
+    /**
+     * Whether the field is required
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Child form control (Input, Select, Textarea, etc.)
+     */
+    children: React.ReactElement<FormControlProps>;
+    /**
+     * Additional class name
+     */
+    className?: string;
+    /**
+     * Label position
+     * @default 'top'
+     */
+    labelPosition?: 'top' | 'left' | 'right';
+    /**
+     * Hide the label visually (still accessible)
+     * @default false
+     */
+    hideLabel?: boolean;
+}
+/**
+ * FormField component for wrapping form controls
+ *
+ * Automatically connects to Form context for:
+ * - Value binding
+ * - Error display
+ * - Touched state
+ * - Accessibility (labels, descriptions)
+ *
+ * @example
+ * ```tsx
+ * <Form initialValues={{ email: '' }} onSubmit={handleSubmit}>
+ *   <FormField name="email" label="Email" required helperText="We'll never share your email">
+ *     <Input type="email" placeholder="Enter your email" />
+ *   </FormField>
+ * </Form>
+ * ```
+ */
+export declare const FormField: React.FC<FormFieldProps>;
+export {};

package/lib/Input.d.ts

@@ -0,0 +1,89 @@
+import { default as React } from 'react';
+export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'prefix' | 'onCopy'> {
+    /**
+     * Label text for the input
+     */
+    label?: string;
+    /**
+     * Validation/interaction status
+     * @default 'default'
+     */
+    status?: 'default' | 'success' | 'error' | 'pending';
+    /**
+     * Helper text displayed below the input
+     */
+    helperText?: string;
+    /**
+     * Whether the field is required
+     */
+    required?: boolean;
+    /**
+     * Icon or element displayed on the left side of the input
+     */
+    leftIcon?: React.ReactNode;
+    /**
+     * Icon or element displayed on the right side of the input
+     */
+    rightIcon?: React.ReactNode;
+    /**
+     * Vertical alignment of icons relative to input
+     * @default 'center'
+     */
+    iconAlign?: 'top' | 'center';
+    /**
+     * Shows clear button when input has value
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * Callback when clear button is clicked
+     */
+    onClear?: () => void;
+    /**
+     * Shows copy button to copy input value
+     * @default false
+     */
+    copyable?: boolean;
+    /**
+     * Callback after successful copy
+     */
+    onCopy?: (value: string) => void;
+    /**
+     * Show character counter (requires maxLength to be set)
+     * @default false
+     */
+    showCounter?: boolean;
+    /**
+     * Custom counter renderer
+     */
+    renderCounter?: (current: number, max: number) => React.ReactNode;
+    /**
+     * @deprecated Use leftIcon instead
+     * Prefix text or element displayed before the input (e.g., "$" for currency)
+     */
+    prefix?: React.ReactNode;
+    /**
+     * @deprecated Use rightIcon instead
+     * Suffix text or element displayed after the input
+     */
+    suffix?: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * Input component with label, status indicators, and helper text
+ *
+ * DOM Structure:
+ * - If label/helper present: wraps in `.gloss-input-anatomy`
+ * - Input: `<input class="gloss-input gloss-input--{status}">`
+ *
+ * @example
+ * ```tsx
+ * <Input label="Email" placeholder="name@example.com" />
+ * <Input label="Username" status="success" helperText="Available!" />
+ * <Input label="Password" status="error" helperText="Too short" required />
+ * ```
+ */
+export declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;

package/lib/InputGroup.d.ts

@@ -0,0 +1,59 @@
+import { default as React } from 'react';
+export interface InputGroupProps {
+    /**
+     * Child elements (Inputs, InputAddons, Buttons)
+     */
+    children: React.ReactNode;
+    /**
+     * Visual style for connected inputs (removes gaps, merges borders)
+     * @default false
+     */
+    attached?: boolean;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+export interface InputAddonProps {
+    /**
+     * Addon content (text, icon, etc.)
+     */
+    children: React.ReactNode;
+    /**
+     * Position in group (affects border radius)
+     * @default 'left'
+     */
+    position?: 'left' | 'right';
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * InputGroup component for grouping inputs with addons
+ *
+ * @example
+ * ```tsx
+ * <InputGroup attached>
+ *   <InputAddon position="left">https://</InputAddon>
+ *   <Input placeholder="example.com" />
+ * </InputGroup>
+ *
+ * <InputGroup attached>
+ *   <InputAddon position="left">$</InputAddon>
+ *   <Input type="number" placeholder="0.00" />
+ *   <InputAddon position="right">.00</InputAddon>
+ * </InputGroup>
+ * ```
+ */
+export declare const InputGroup: React.ForwardRefExoticComponent<InputGroupProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * InputAddon component for prepending/appending content to inputs
+ *
+ * @example
+ * ```tsx
+ * <InputAddon position="left">@</InputAddon>
+ * <InputAddon position="right">.com</InputAddon>
+ * ```
+ */
+export declare const InputAddon: React.ForwardRefExoticComponent<InputAddonProps & React.RefAttributes<HTMLSpanElement>>;

package/lib/Link.d.ts

@@ -0,0 +1,69 @@
+import { default as React } from 'react';
+import { IconValue } from './types/icon';
+export type LinkVariant = 'default' | 'muted' | 'danger';
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+    /**
+     * URL the link points to
+     */
+    href?: string;
+    /**
+     * Visual style variant
+     * @default 'default'
+     */
+    variant?: LinkVariant;
+    /**
+     * Size of the link text
+     * @default 'md'
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Icon displayed before the link text
+     */
+    leftIcon?: IconValue;
+    /**
+     * Icon displayed after the link text
+     */
+    rightIcon?: IconValue;
+    /**
+     * Opens link in new tab with security attributes (adds external-link icon)
+     */
+    external?: boolean;
+    /**
+     * Disabled state - prevents interaction
+     */
+    disabled?: boolean;
+    /**
+     * Underline behavior
+     * @default 'hover'
+     */
+    underline?: 'always' | 'hover' | 'none';
+    /**
+     * Render as different element (e.g., for Next.js Link integration)
+     * When using with Next.js, pass the Link component from next/link as `as`
+     * and spread href and other props through
+     */
+    as?: React.ElementType;
+    /**
+     * Content of the link
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * Link component for navigation with consistent styling
+ *
+ * Features underline animations, icons, and external link handling.
+ * Can be composed with framework-specific link components using the `as` prop.
+ *
+ * @example
+ * ```tsx
+ * <Link href="/about">About Us</Link>
+ * <Link href="https://example.com" external>External Site</Link>
+ * <Link href="/settings" leftIcon="settings">Settings</Link>
+ * <Link variant="muted" size="sm">Learn more</Link>
+ * ```
+ */
+export declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;

package/lib/MaskedInput.d.ts

@@ -0,0 +1,95 @@
+import { default as React } from 'react';
+import { default as IMask } from 'imask';
+import { InputProps } from './Input';
+/**
+ * Mask configuration options
+ * @see https://imask.js.org/guide.html
+ */
+export interface MaskConfig {
+    /**
+     * Mask pattern string (e.g., '0000 0000 0000 0000' for credit card)
+     * '0' = digit, 'a' = letter, '*' = any character
+     */
+    mask: string | RegExp | NumberConstructor | Array<string | RegExp | {
+        mask: string;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Placeholder character for unfilled positions
+     * @default '_'
+     */
+    placeholderChar?: string;
+    /**
+     * Whether to show placeholder characters (lazy mode hides unfilled)
+     * @default true
+     */
+    lazy?: boolean;
+    /**
+     * Custom definitions for mask characters
+     * @example { '#': /[0-9]/ }
+     */
+    definitions?: Record<string, RegExp>;
+    /**
+     * Whether to include mask characters in the value
+     * false = masked value, true = unmasked value, 'typed' = typed value
+     * @default false
+     */
+    unmask?: boolean | 'typed';
+    /**
+     * Additional imask options
+     */
+    [key: string]: unknown;
+}
+type IMaskInstance = ReturnType<typeof IMask>;
+/**
+ * Built-in mask presets for common use cases
+ */
+export declare const MaskPresets: Record<string, MaskConfig>;
+export type MaskPresetName = keyof typeof MaskPresets;
+export interface MaskedInputProps extends Omit<InputProps, 'onChange' | 'value'> {
+    /**
+     * Mask configuration object or preset name
+     */
+    mask: MaskConfig | MaskPresetName;
+    /**
+     * Current value (can be masked or unmasked depending on mask config)
+     */
+    value?: string;
+    /**
+     * Callback with unmasked value when input is accepted
+     */
+    onAccept?: (value: string, maskRef: IMaskInstance) => void;
+    /**
+     * Callback when mask is complete
+     */
+    onComplete?: (value: string, maskRef: IMaskInstance) => void;
+    /**
+     * Standard onChange for form compatibility (fires with masked value)
+     */
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}
+/**
+ * Input component with built-in masking support
+ *
+ * Wraps the base Input component with imask integration for
+ * formatted input like credit cards, phone numbers, dates, etc.
+ *
+ * @example
+ * ```tsx
+ * // Using a preset
+ * <MaskedInput
+ *   mask="creditCard"
+ *   label="Card Number"
+ *   onAccept={(value) => setCardNumber(value)}
+ * />
+ *
+ * // Custom mask
+ * <MaskedInput
+ *   mask={{ mask: '000-000-0000' }}
+ *   label="Phone"
+ *   onAccept={(value) => setPhone(value)}
+ * />
+ * ```
+ */
+export declare const MaskedInput: React.ForwardRefExoticComponent<MaskedInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/lib/Menu.d.ts

@@ -0,0 +1,132 @@
+import { default as React } from 'react';
+import { AccordionShowCount } from './Accordion';
+export type MenuLevel = 0 | 1 | 2;
+export interface MenuProps extends React.HTMLAttributes<HTMLElement> {
+    /**
+     * Content of the menu (MenuGroup or MenuItem components)
+     */
+    children: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * Menu - navigation container with collapsible groups
+ *
+ * DOM Structure: `<nav class="gloss-menu">`
+ *
+ * @example
+ * ```tsx
+ * <Menu>
+ *   <MenuGroup label="Components" showCount="never">
+ *     <MenuGroup label="Input" showCount="collapsed-only">
+ *       <MenuItem href="/input" icon={<Icon name="input" />}>Text</MenuItem>
+ *     </MenuGroup>
+ *   </MenuGroup>
+ * </Menu>
+ * ```
+ */
+export declare const Menu: React.ForwardRefExoticComponent<MenuProps & React.RefAttributes<HTMLElement>>;
+export interface MenuGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Label text for the group header
+     */
+    label: string;
+    /**
+     * Icon to display on the left side of the header
+     */
+    icon?: React.ReactNode;
+    /**
+     * Whether the group is expanded by default
+     */
+    defaultOpen?: boolean;
+    /**
+     * Controlled open state
+     */
+    open?: boolean;
+    /**
+     * Callback when open state changes
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * When to show the item count badge
+     */
+    showCount?: AccordionShowCount;
+    /**
+     * Whether the group is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Content of the group (MenuItem or nested MenuGroup)
+     */
+    children: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * MenuGroup - collapsible section within Menu
+ *
+ * DOM Structure: `<div class="gloss-menu-group">`
+ */
+export declare const MenuGroup: React.ForwardRefExoticComponent<MenuGroupProps & React.RefAttributes<HTMLDivElement>>;
+export interface MenuItemProps extends React.HTMLAttributes<HTMLElement> {
+    /**
+     * URL for the item (renders as anchor if provided)
+     */
+    href?: string;
+    /**
+     * Custom component to render as (e.g., Next.js Link)
+     * When provided with href, renders the component with href prop
+     */
+    as?: React.ElementType;
+    /**
+     * Icon to display on the left side
+     */
+    icon?: React.ReactNode;
+    /**
+     * Whether the item is currently active/selected
+     */
+    active?: boolean;
+    /**
+     * Whether the item is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Click handler (for non-link items)
+     */
+    onClick?: (e: React.MouseEvent) => void;
+    /**
+     * Content of the item
+     */
+    children: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * MenuItem - individual navigation item
+ *
+ * DOM Structure: `<a class="gloss-menu-item">` or `<button class="gloss-menu-item">`
+ *
+ * @example
+ * // With Next.js Link
+ * import Link from 'next/link';
+ * <MenuItem as={Link} href="/dashboard" icon={<Icon name="home" />}>Dashboard</MenuItem>
+ */
+export declare const MenuItem: React.ForwardRefExoticComponent<MenuItemProps & React.RefAttributes<HTMLElement>>;
+export interface MenuDividerProps extends React.HTMLAttributes<HTMLHRElement> {
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * MenuDivider - visual separator between menu items
+ *
+ * DOM Structure: `<hr class="gloss-menu-divider">`
+ */
+export declare const MenuDivider: React.ForwardRefExoticComponent<MenuDividerProps & React.RefAttributes<HTMLHRElement>>;