@orion-ds/react 1.1.2 → 1.1.4

package/dist/components/Button/Button.types.d.ts

@@ -2,62 +2,181 @@
  * Button Component Types
  *
  * Type definitions for the Orion Button component.
+ *
+ * @module Button
+ * @see {@link ./README.md} for full documentation
  */
 import type { ButtonHTMLAttributes, ReactNode } from 'react';
 /**
- * Button visual variants
+ * Button visual variants - each has specific semantic meaning.
+ *
+ * @semanticGuide
+ * - `primary`: Main CTA - Submit, Save, Continue, Get Started
+ * - `secondary`: Supporting action - Cancel, Back, Learn More
+ * - `ghost`: Subtle/tertiary action - Close, Dismiss, Skip
+ * - `danger`: Destructive action - Delete, Remove, Unsubscribe
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary">Save</Button>      // Main action
+ * <Button variant="secondary">Cancel</Button>  // Supporting action
+ * <Button variant="ghost">Skip</Button>        // Subtle action
+ * <Button variant="danger">Delete</Button>     // Destructive action
+ * ```
  */
 export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
 /**
- * Button sizes
+ * Button sizes - automatically adapt to current mode (display/product/app).
+ *
+ * @modeAware Sizes scale per data-mode:
+ * - Display mode: sm=40px, md=56px, lg=64px (spacious, marketing)
+ * - Product mode: sm=28px, md=32px, lg=36px (compact, SaaS)
+ * - App mode: sm=40px, md=44px, lg=48px (touch-friendly, mobile)
+ *
+ * @semanticGuide
+ * - `sm`: Dense UIs, tables, inline actions
+ * - `md`: Default - most buttons (recommended)
+ * - `lg`: Hero CTAs, prominent actions
+ *
+ * @example
+ * ```tsx
+ * <Button size="sm">Edit</Button>           // Dense UI
+ * <Button size="md">Submit</Button>         // Default
+ * <Button size="lg">Get Started</Button>    // Hero CTA
+ * ```
  */
 export type ButtonSize = 'sm' | 'md' | 'lg';
 /**
  * Button component props
  *
- * @example
+ * @example Basic usage
  * ```tsx
  * <Button variant="primary" size="md">
  *   Click me
  * </Button>
  * ```
+ *
+ * @example With icon
+ * ```tsx
+ * import { Download } from 'lucide-react';
+ *
+ * <Button icon={<Download size={20} />}>
+ *   Download
+ * </Button>
+ * ```
+ *
+ * @example Icon-only (requires aria-label)
+ * ```tsx
+ * import { Settings } from 'lucide-react';
+ *
+ * <Button
+ *   iconOnly
+ *   icon={<Settings size={20} />}
+ *   aria-label="Settings"
+ * />
+ * ```
+ *
+ * @example Loading state
+ * ```tsx
+ * <Button isLoading>
+ *   Saving...
+ * </Button>
+ * ```
  */
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     /**
-     * Visual variant of the button
+     * Visual variant of the button.
+     *
+     * @semanticGuide
+     * - `primary`: Main CTA (Submit, Save, Continue)
+     * - `secondary`: Supporting action (Cancel, Back)
+     * - `ghost`: Subtle action (Close, Dismiss)
+     * - `danger`: Destructive action (Delete, Remove)
+     *
      * @default 'primary'
      */
     variant?: ButtonVariant;
     /**
-     * Size of the button
+     * Size of the button. Automatically adapts to current mode.
+     *
+     * @modeAware
+     * - Display: 40/56/64px heights (spacious)
+     * - Product: 28/32/36px heights (compact)
+     * - App: 40/44/48px heights (touch-friendly)
+     *
      * @default 'md'
      */
     size?: ButtonSize;
     /**
-     * Loading state - shows spinner and disables interaction
+     * Loading state - shows spinner and disables interaction.
+     * Button text remains visible but dimmed.
+     *
+     * @example
+     * ```tsx
+     * <Button isLoading>Saving...</Button>
+     * ```
+     *
      * @default false
      */
     isLoading?: boolean;
     /**
-     * Full width button
+     * Full width button - expands to fill container.
+     * Useful for form submissions and card footers.
+     *
+     * @example
+     * ```tsx
+     * <Card.Footer>
+     *   <Button fullWidth>Continue</Button>
+     * </Card.Footer>
+     * ```
+     *
      * @default false
      */
     fullWidth?: boolean;
     /**
-     * Icon to display (left side)
+     * Icon to display on the left side of button text.
+     * Use 20px icons (size={20}) for best results.
+     *
+     * @example
+     * ```tsx
+     * import { Download } from 'lucide-react';
+     * <Button icon={<Download size={20} />}>Download</Button>
+     * ```
      */
     icon?: ReactNode;
     /**
-     * Icon to display (right side)
+     * Icon to display on the right side of button text.
+     * Commonly used for chevrons/arrows indicating action direction.
+     *
+     * @example
+     * ```tsx
+     * import { ChevronRight } from 'lucide-react';
+     * <Button iconRight={<ChevronRight size={20} />}>Continue</Button>
+     * ```
      */
     iconRight?: ReactNode;
     /**
-     * Icon-only button (no text)
+     * Icon-only button (no text, just icon).
+     *
+     * @requires aria-label - MUST provide aria-label for accessibility
+     *
+     * @example
+     * ```tsx
+     * import { Settings } from 'lucide-react';
+     *
+     * // CORRECT - has aria-label
+     * <Button iconOnly icon={<Settings size={20} />} aria-label="Settings" />
+     *
+     * // WRONG - missing aria-label (accessibility violation)
+     * <Button iconOnly icon={<Settings size={20} />} />
+     * ```
+     *
      * @default false
      */
     iconOnly?: boolean;
     /**
-     * Button content
+     * Button content (text and/or elements).
+     * Ignored when iconOnly is true.
      */
     children?: ReactNode;
 }

package/dist/components/Button/Button.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Button.types.d.ts","sourceRoot":"","sources":["../../../src/components/Button/Button.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAY,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IAC1E;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB"}
+{"version":3,"file":"Button.types.d.ts","sourceRoot":"","sources":["../../../src/components/Button/Button.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,WAAY,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IAC1E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB"}

package/dist/components/Field/Field.types.d.ts

@@ -2,54 +2,167 @@
  * Field Component Types
  *
  * Type definitions for the Orion Field component (input with label and error).
+ *
+ * @important Field is a SELF-CONTAINED component - it renders its own input.
+ * Do NOT use children to pass an input element.
+ *
+ * @module Field
+ * @see {@link ./README.md} for full documentation
  */
 import type { InputHTMLAttributes, ReactNode } from 'react';
 /**
  * Field component props
  *
- * @example
+ * @important Field is PROPS-BASED, not a wrapper. It renders its own `<input>`.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Field
+ *   label="Email"
+ *   type="email"
+ *   placeholder="you@example.com"
+ * />
+ * ```
+ *
+ * @example With validation error
+ * ```tsx
+ * <Field
+ *   label="Email"
+ *   type="email"
+ *   value={email}
+ *   onChange={(e) => setEmail(e.target.value)}
+ *   error={emailError}
+ * />
+ * ```
+ *
+ * @example With icons
  * ```tsx
+ * import { Mail, Eye } from 'lucide-react';
+ *
  * <Field
  *   label="Email"
  *   type="email"
- *   placeholder="Enter your email"
- *   error="Invalid email address"
+ *   leftIcon={<Mail size={18} />}
+ *   placeholder="you@example.com"
  * />
  * ```
+ *
+ * @example WRONG - Don't use children
+ * ```tsx
+ * // WRONG - Field doesn't accept children for input
+ * <Field label="Email">
+ *   <input type="email" />  // This won't work!
+ * </Field>
+ *
+ * // CORRECT - Use props
+ * <Field label="Email" type="email" />
+ * ```
  */
 export interface FieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /**
-     * Input label text
+     * Input label text displayed above the input.
+     * Required for accessibility unless aria-label is provided.
+     *
+     * @example
+     * ```tsx
+     * <Field label="Email Address" type="email" />
+     * ```
      */
     label?: string;
     /**
-     * Error message (shows error state when present)
+     * Error message - shows error state and displays message below input.
+     * Takes precedence over helperText when both are provided.
+     * Automatically associated with input via aria-describedby.
+     *
+     * @example
+     * ```tsx
+     * <Field
+     *   label="Email"
+     *   type="email"
+     *   error="Please enter a valid email address"
+     * />
+     * ```
      */
     error?: string;
     /**
-     * Helper text (shown below input)
+     * Helper text displayed below input (when no error).
+     * Provides additional context or instructions.
+     *
+     * @example
+     * ```tsx
+     * <Field
+     *   label="Password"
+     *   type="password"
+     *   helperText="Must be at least 8 characters"
+     * />
+     * ```
      */
     helperText?: string;
     /**
-     * Icon to display on the left
+     * Icon to display on the left side of input.
+     * Use 18px icons (size={18}) for best results.
+     *
+     * @example
+     * ```tsx
+     * import { Mail } from 'lucide-react';
+     * <Field leftIcon={<Mail size={18} />} label="Email" type="email" />
+     * ```
      */
     leftIcon?: ReactNode;
     /**
-     * Icon to display on the right
+     * Icon to display on the right side of input.
+     * Can be an icon or interactive element (e.g., password toggle).
+     *
+     * @example
+     * ```tsx
+     * import { Eye, EyeOff } from 'lucide-react';
+     *
+     * <Field
+     *   label="Password"
+     *   type={showPassword ? 'text' : 'password'}
+     *   rightIcon={
+     *     <button onClick={() => setShowPassword(!showPassword)}>
+     *       {showPassword ? <EyeOff size={18} /> : <Eye size={18} />}
+     *     </button>
+     *   }
+     * />
+     * ```
      */
     rightIcon?: ReactNode;
     /**
-     * Full width input
+     * Full width input - expands to fill container.
+     *
+     * @example
+     * ```tsx
+     * <form style={{ maxWidth: '400px' }}>
+     *   <Field label="Name" fullWidth />
+     *   <Field label="Email" type="email" fullWidth />
+     * </form>
+     * ```
+     *
      * @default false
      */
     fullWidth?: boolean;
     /**
-     * Input size
+     * Input size variant.
+     *
+     * @semanticGuide
+     * - `sm`: Dense UIs, tables, compact forms
+     * - `md`: Default - most forms (recommended)
+     * - `lg`: Prominent forms, search inputs
+     *
      * @default 'md'
      */
     size?: 'sm' | 'md' | 'lg';
     /**
-     * Optional indicator
+     * Shows "(optional)" indicator next to label.
+     * Use when most fields are required but some are optional.
+     *
+     * @example
+     * ```tsx
+     * <Field label="Phone Number" type="tel" optional />
+     * ```
+     *
      * @default false
      */
     optional?: boolean;

package/dist/components/Field/Field.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Field.types.d.ts","sourceRoot":"","sources":["../../../src/components/Field/Field.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACrF;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
+{"version":3,"file":"Field.types.d.ts","sourceRoot":"","sources":["../../../src/components/Field/Field.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACrF;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/contexts/ThemeContext.d.ts

@@ -4,6 +4,8 @@
  * Provides global theme and brand state to all components.
  * This ensures consistent theming across the entire application.
  *
+ * Fonts are loaded automatically by default. No need to add <FontLoader /> manually.
+ *
  * @example
  * ```tsx
  * // App.tsx
@@ -24,6 +26,11 @@
  *   const { theme, brand } = useTheme();
  *   return <div>Current: {theme} / {brand}</div>;
  * }
+ *
+ * // To disable automatic font loading:
+ * <ThemeProvider disableAutoFontLoading>
+ *   <YourComponents />
+ * </ThemeProvider>
  * ```
  */
 import { ReactNode } from 'react';
@@ -45,6 +52,13 @@ export interface ThemeProviderProps {
      * @default false
      */
     disableFontWarnings?: boolean;
+    /**
+     * Disable automatic font loading via FontLoader
+     * When false (default), fonts are loaded automatically.
+     * Set to true if you want to manage font loading manually.
+     * @default false
+     */
+    disableAutoFontLoading?: boolean;
 }
 /**
  * ThemeProvider Component
@@ -52,7 +66,7 @@ export interface ThemeProviderProps {
  * Wraps your application to provide global theme and brand state.
  * Must be placed near the root of your application.
  */
-export declare function ThemeProvider({ children, options, disableFontWarnings }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ThemeProvider({ children, options, disableFontWarnings, disableAutoFontLoading, }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Hook to access global theme state
  *

package/dist/contexts/ThemeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThemeContext.d.ts","sourceRoot":"","sources":["../../src/contexts/ThemeContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAgD,SAAS,EAAE,MAAM,OAAO,CAAC;AAChF,OAAO,EAA4B,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAQ9F;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,mBAA2B,EAAE,EAAE,kBAAkB,2CA+CnG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,cAAc,CAmBhD"}
+{"version":3,"file":"ThemeContext.d.ts","sourceRoot":"","sources":["../../src/contexts/ThemeContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAgD,SAAS,EAAE,MAAM,OAAO,CAAC;AAChF,OAAO,EAA4B,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAS9F;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,OAAO,EACP,mBAA2B,EAC3B,sBAA8B,GAC/B,EAAE,kBAAkB,2CAoDpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,cAAc,CAmBhD"}

package/dist/examples/LandingPage.example.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Landing Page Example
+ *
+ * A complete, copy-paste ready landing page using @orion/react sections.
+ * This example demonstrates the recommended structure and composition
+ * of Orion sections for building marketing pages.
+ *
+ * @example Usage
+ * ```tsx
+ * // In your app
+ * import { LandingPageExample } from '@orion/react/examples';
+ *
+ * function App() {
+ *   return <LandingPageExample />;
+ * }
+ * ```
+ *
+ * @module examples
+ */
+import React from 'react';
+/**
+ * Complete Landing Page Example
+ *
+ * This component demonstrates the recommended structure for building
+ * landing pages with @orion/react sections. Copy and customize for your needs.
+ *
+ * @remarks
+ * IMPORTANT: In your actual app, you must import the CSS files at the root:
+ * ```tsx
+ * import '@orion/core/theme.css';
+ * import '@orion/react/dist/react.css';
+ * ```
+ */
+export declare function LandingPageExample(): React.ReactElement;
+export default LandingPageExample;
+//# sourceMappingURL=LandingPage.example.d.ts.map

package/dist/examples/LandingPage.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LandingPage.example.d.ts","sourceRoot":"","sources":["../../src/examples/LandingPage.example.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAoO1B;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,KAAK,CAAC,YAAY,CAqJvD;AAED,eAAe,kBAAkB,CAAC"}

package/dist/examples/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @orion/react Examples
+ *
+ * Complete, copy-paste ready examples demonstrating how to use
+ * Orion components and sections together.
+ *
+ * @example
+ * ```tsx
+ * import { LandingPageExample } from '@orion/react';
+ *
+ * // Use directly for testing
+ * function App() {
+ *   return <LandingPageExample />;
+ * }
+ *
+ * // Or study the source code to build your own
+ * ```
+ *
+ * @module examples
+ */
+export { LandingPageExample } from './LandingPage.example';
+//# sourceMappingURL=index.d.ts.map

package/dist/examples/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/examples/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}