@graphty/compact-mantine 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -1,10 +1,14 @@
+import { ActionIconProps } from '@mantine/core';
 import { default as default_2 } from 'react';
+import { ForwardRefExoticComponent } from 'react';
 import { JSX } from 'react';
 import { MantineColorShade } from '@mantine/core';
 import { MantineColorsTuple } from '@mantine/core';
 import { MantineRadius } from '@mantine/core';
+import { MantineTheme } from '@mantine/core';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
+import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import { VariantColorsResolver } from '@mantine/core';
 
@@ -20,6 +24,33 @@ export declare interface ColorStop {
     color: string;
 }
 
+/**
+ * Compact theme sizing constants.
+ * These values represent the standard sizing used throughout the compact theme
+ * for consistent component dimensions. Use these when creating custom components
+ * that need to match the compact theme's sizing.
+ * @example
+ * ```tsx
+ * import { COMPACT_SIZING } from '@graphty/compact-mantine';
+ *
+ * const MyComponent = () => (
+ *   <div style={{ height: COMPACT_SIZING.HEIGHT, fontSize: COMPACT_SIZING.FONT_SIZE }}>
+ *     Custom compact component
+ *   </div>
+ * );
+ * ```
+ */
+export declare const COMPACT_SIZING: {
+    /** Standard compact component height (inputs, buttons, icons) in pixels */
+    readonly HEIGHT: 24;
+    /** Standard compact font size in pixels */
+    readonly FONT_SIZE: 11;
+    /** Standard padding for control elements in pixels */
+    readonly CONTROL_PADDING: 8;
+    /** Gap between items in sections/lists in pixels */
+    readonly SECTION_GAP: 4;
+};
+
 /**
  * Compact color input with optional opacity support.
  * Supports both controlled and uncontrolled modes.
@@ -64,9 +95,23 @@ export declare interface CompactColorInputProps {
 
 /**
  * Color configuration for the compact theme.
+ * Includes all default Mantine colors plus custom dark palette.
  */
 export declare const compactColors: {
     dark: MantineColorsTuple;
+    gray: MantineColorsTuple;
+    red: MantineColorsTuple;
+    pink: MantineColorsTuple;
+    grape: MantineColorsTuple;
+    violet: MantineColorsTuple;
+    indigo: MantineColorsTuple;
+    blue: MantineColorsTuple;
+    cyan: MantineColorsTuple;
+    green: MantineColorsTuple;
+    lime: MantineColorsTuple;
+    yellow: MantineColorsTuple;
+    orange: MantineColorsTuple;
+    teal: MantineColorsTuple;
 };
 
 /**
@@ -81,49 +126,79 @@ export declare const compactColors: {
 export declare const compactDarkColors: MantineColorsTuple;
 
 /**
- * Mantine theme with "compact" size support for dense UIs.
+ * Full Mantine theme with compact sizing by default for dense UIs.
  *
- * Compact size specifications:
+ * This is a complete theme merged with DEFAULT_THEME, suitable for:
+ * - Direct use with MantineProvider
+ * - Merging with other themes using mergeMantineTheme()
+ *
+ * All components default to size="sm" automatically with compact styling:
  * - Input height: 24px
  * - Font size: 11px
  * - No borders
  * - Semantic color backgrounds
+ *
+ * Global token overrides:
+ * - fontSizes: Smaller font sizes (xs: 10px, sm: 11px, md: 13px, lg: 14px, xl: 16px)
+ * - spacing: Tighter spacing (xs: 4px, sm: 6px, md: 8px, lg: 12px, xl: 16px)
+ * - radius: Compact corner radii (xs: 2px, sm: 4px, md: 6px, lg: 8px, xl: 12px)
+ * @example
+ * ```tsx
+ * // Simple usage - direct with MantineProvider
+ * import { MantineProvider } from '@mantine/core';
+ * import { compactTheme } from '@graphty/compact-mantine';
+ *
+ * <MantineProvider theme={compactTheme}>
+ *     <App />
+ * </MantineProvider>
+ * ```
  * @example
  * ```tsx
- * import { MantineProvider, TextInput } from '@mantine/core';
+ * // Extending the theme with mergeMantineTheme
+ * import { mergeMantineTheme, createTheme } from '@mantine/core';
  * import { compactTheme } from '@graphty/compact-mantine';
  *
- * function App() {
- *     return (
- *         <MantineProvider theme={compactTheme}>
- *             <TextInput size="compact" label="Name" />
- *         </MantineProvider>
- *     );
- * }
+ * const myTheme = mergeMantineTheme(compactTheme, createTheme({
+ *     primaryColor: 'teal',
+ * }));
+ *
+ * <MantineProvider theme={myTheme}>
+ *     <App />
+ * </MantineProvider>
  * ```
  */
-export declare const compactTheme: {
-    focusRing?: "auto" | "always" | "never" | undefined;
+export declare const compactTheme: MantineTheme;
+
+/**
+ * Partial theme override with compact sizing for dense UIs.
+ *
+ * This is the raw theme override created with createTheme().
+ * Use this if you need to merge with other theme overrides using mergeThemeOverrides().
+ *
+ * For most use cases, use `compactTheme` instead which is a full merged theme.
+ */
+export declare const compactThemeOverride: {
+    focusRing?: "auto" | "never" | "always" | undefined;
     scale?: number | undefined;
     fontSmoothing?: boolean | undefined;
     white?: string | undefined;
     black?: string | undefined;
     colors?: {
         [x: string & {}]: MantineColorsTuple | undefined;
+        dark?: MantineColorsTuple | undefined;
+        gray?: MantineColorsTuple | undefined;
+        red?: MantineColorsTuple | undefined;
+        pink?: MantineColorsTuple | undefined;
+        grape?: MantineColorsTuple | undefined;
+        violet?: MantineColorsTuple | undefined;
+        indigo?: MantineColorsTuple | undefined;
         blue?: MantineColorsTuple | undefined;
         cyan?: MantineColorsTuple | undefined;
-        gray?: MantineColorsTuple | undefined;
         green?: MantineColorsTuple | undefined;
-        indigo?: MantineColorsTuple | undefined;
         lime?: MantineColorsTuple | undefined;
+        yellow?: MantineColorsTuple | undefined;
         orange?: MantineColorsTuple | undefined;
-        pink?: MantineColorsTuple | undefined;
-        red?: MantineColorsTuple | undefined;
         teal?: MantineColorsTuple | undefined;
-        violet?: MantineColorsTuple | undefined;
-        yellow?: MantineColorsTuple | undefined;
-        dark?: MantineColorsTuple | undefined;
-        grape?: MantineColorsTuple | undefined;
     } | undefined;
     primaryShade?: MantineColorShade | {
         light?: MantineColorShade | undefined;
@@ -251,9 +326,10 @@ export declare const compactTheme: {
  * @param root0.label - The label text for the group header
  * @param root0.actions - Optional action buttons to display in the header
  * @param root0.children - Child controls to render in the group
+ * @param root0.bleed - When true, separator line extends to parent container edges
  * @returns The control group component
  */
-export declare function ControlGroup({ label, actions, children }: ControlGroupProps): default_2.JSX.Element;
+export declare function ControlGroup({ label, actions, children, bleed }: ControlGroupProps): default_2.JSX.Element;
 
 /**
  * Props for the ControlGroup component.
@@ -265,6 +341,12 @@ export declare interface ControlGroupProps {
     actions?: ReactNode;
     /** Group content */
     children: ReactNode;
+    /**
+     * When true, the separator line extends beyond the component boundaries
+     * to reach the edges of the parent container (useful inside Popouts with padding).
+     * Uses negative margins to counteract the parent's padding.
+     */
+    bleed?: boolean;
 }
 
 /**
@@ -342,38 +424,6 @@ export declare function createDefaultGradientStops(): ColorStop[];
  */
 export declare const DEFAULT_GRADIENT_STOP_COLOR = "#888888";
 
-/**
- * A checkbox toggle that shows/hides child controls.
- * Supports both controlled and uncontrolled modes.
- * Used for enabling/disabling effects like glow and outline.
- * Provides clean visual indent for child content.
- * @param root0 - Component props
- * @param root0.label - The label for the toggle checkbox
- * @param root0.checked - Whether the toggle is checked (controlled mode)
- * @param root0.defaultChecked - Default checked state for uncontrolled mode
- * @param root0.onChange - Called when the toggle state changes (optional for uncontrolled mode)
- * @param root0.children - Child controls to show when checked
- * @returns The effect toggle component
- */
-export declare function EffectToggle({ label, checked, defaultChecked, onChange, children, }: EffectToggleProps): default_2.JSX.Element;
-
-/**
- * Props for EffectToggle component.
- * Supports both controlled and uncontrolled modes via useUncontrolled pattern.
- */
-export declare interface EffectToggleProps {
-    /** Checkbox label */
-    label: string;
-    /** Whether effect is enabled (controlled mode) */
-    checked?: boolean;
-    /** Default checked state for uncontrolled mode */
-    defaultChecked?: boolean;
-    /** Called when checked state changes (optional for uncontrolled mode) */
-    onChange?: (checked: boolean) => void;
-    /** Content shown when checked */
-    children: ReactNode;
-}
-
 /**
  * Editor for gradient color stops with optional direction control.
  * Supports both controlled and uncontrolled modes.
@@ -468,6 +518,7 @@ export declare const Popout: typeof PopoutRoot & {
     Trigger: typeof PopoutTrigger;
     Panel: typeof PopoutPanel;
     Content: typeof PopoutContent;
+    Anchor: typeof PopoutAnchor;
 };
 
 /**
@@ -495,6 +546,72 @@ export declare const POPOUT_Z_INDEX_BASE = 1000;
  */
 declare type PopoutAlignment = "start" | "center" | "end";
 
+/**
+ * Provides an anchor element for descendant Popout panels to align to.
+ *
+ * When a Popout.Panel is inside a PopoutAnchor and doesn't have an explicit
+ * `anchorRef` prop, it will automatically align to the anchor element.
+ *
+ * This is useful for sidebars, control panels, or any container where you
+ * want popouts to align to the container edge rather than just the trigger.
+ * @param props - Component props
+ * @param props.children - The container element (must accept a ref)
+ * @returns The PopoutAnchor component
+ * @example
+ * ```tsx
+ * <Popout.Anchor>
+ *     <Box style={{ width: 240, borderLeft: '1px solid gray' }}>
+ *         <Popout>
+ *             <Popout.Trigger>
+ *                 <PopoutButton icon={<Settings />} aria-label="Settings" />
+ *             </Popout.Trigger>
+ *             <Popout.Panel width={280} header={{ variant: "title", title: "Settings" }}>
+ *                 <Popout.Content>Content aligns to sidebar edge</Popout.Content>
+ *             </Popout.Panel>
+ *         </Popout>
+ *     </Box>
+ * </Popout.Anchor>
+ * ```
+ */
+declare function PopoutAnchor({ children }: PopoutAnchorProps): JSX.Element;
+
+/**
+ * Props for PopoutAnchor.
+ */
+declare interface PopoutAnchorProps {
+    /** The container element to use as anchor. Must accept a ref. */
+    children: ReactNode;
+}
+
+/**
+ * A button component designed to be used as a Popout trigger.
+ * Automatically highlights when the associated popout is open.
+ * Features:
+ * - Uses `subtle` variant when popout is closed (dimmed appearance)
+ * - Uses `light` variant when popout is open (highlighted appearance)
+ * - Must be used within a Popout component (inside Popout.Trigger)
+ * @example
+ * ```tsx
+ * <Popout>
+ *     <Popout.Trigger>
+ *         <PopoutButton icon={<Settings size={12} />} aria-label="Open settings" />
+ *     </Popout.Trigger>
+ *     <Popout.Panel width={280} header={{ variant: "title", title: "Settings" }}>
+ *         <Popout.Content>Content here</Popout.Content>
+ *     </Popout.Panel>
+ * </Popout>
+ * ```
+ */
+export declare const PopoutButton: ForwardRefExoticComponent<PopoutButtonProps & RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Props for the PopoutButton component.
+ */
+declare interface PopoutButtonProps extends Omit<ActionIconProps, "variant" | "children"> {
+    /** The icon to display inside the button */
+    icon: ReactNode;
+}
+
 /**
  * Container for popout panel content.
  * Provides consistent padding and styling for panel content.
@@ -898,18 +1015,45 @@ export declare interface StyleSelectProps {
     onChange?: (value: string | undefined) => void;
 }
 
-/**
- * Standard color swatches for color pickers throughout the application.
- * Used by CompactColorInput and GradientEditor.
- */
-export declare const SWATCH_COLORS: readonly ["#5B8FF9", "#FF6B6B", "#61D095", "#F7B731", "#9B59B6"];
-
 /**
  * Swatches with alpha channel for HEXA color pickers.
  * Includes both fully opaque (FF) and semi-transparent (80) variants.
+ * Used by CompactColorInput for color picker swatches.
  */
 export declare const SWATCH_COLORS_HEXA: readonly ["#5B8FF9FF", "#FF6B6BFF", "#61D095FF", "#F7B731FF", "#9B59B6FF", "#5B8FF980", "#FF6B6B80", "#61D09580", "#F7B73180", "#9B59B680"];
 
+/**
+ * A checkbox toggle that shows/hides child controls.
+ * Supports both controlled and uncontrolled modes.
+ * Used for enabling/disabling optional features with nested configuration.
+ * Provides clean visual indent for child content.
+ * @param root0 - Component props
+ * @param root0.label - The label for the toggle checkbox
+ * @param root0.checked - Whether the toggle is checked (controlled mode)
+ * @param root0.defaultChecked - Default checked state for uncontrolled mode
+ * @param root0.onChange - Called when the toggle state changes (optional for uncontrolled mode)
+ * @param root0.children - Child controls to show when checked
+ * @returns The toggle with content component
+ */
+export declare function ToggleWithContent({ label, checked, defaultChecked, onChange, children, }: ToggleWithContentProps): default_2.JSX.Element;
+
+/**
+ * Props for ToggleWithContent component.
+ * Supports both controlled and uncontrolled modes via useUncontrolled pattern.
+ */
+export declare interface ToggleWithContentProps {
+    /** Checkbox label */
+    label: string;
+    /** Whether toggle is enabled (controlled mode) */
+    checked?: boolean;
+    /** Default checked state for uncontrolled mode */
+    defaultChecked?: boolean;
+    /** Called when checked state changes (optional for uncontrolled mode) */
+    onChange?: (checked: boolean) => void;
+    /** Content shown when checked */
+    children: ReactNode;
+}
+
 /**
  * Convert RGB hex and opacity to HEXA format.
  * @param hex - Color in hex format (#RRGGBB)
@@ -921,9 +1065,17 @@ export declare function toHexaColor(hex: string, opacity: number): string;
 /**
  * Hook to get the actual resolved color scheme.
  * Resolves "auto" to the actual light/dark value based on system preference.
- * @returns "light" | "dark"
+ * @param fallback - Fallback color scheme when system preference cannot be determined.
+ *                   Defaults to "dark" for consistency with existing behavior.
+ * @returns "light" | "dark" - The resolved color scheme
+ * @example
+ * // Use default fallback (dark)
+ * const scheme = useActualColorScheme();
+ * @example
+ * // Use custom fallback
+ * const scheme = useActualColorScheme("light");
  */
-export declare function useActualColorScheme(): "light" | "dark";
+export declare function useActualColorScheme(fallback?: "light" | "dark"): "light" | "dark";
 
 export declare const VERSION = "0.1.0";