@idealyst/components 1.1.6 → 1.1.7

package/src/View/View.web.tsx

@@ -1,4 +1,5 @@
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useMemo } from 'react';
+import { StyleSheet } from 'react-native';
 import { getWebProps } from 'react-native-unistyles/web';
 import { ViewProps } from './types';
 import { viewStyles } from './View.styles';
@@ -48,13 +49,23 @@ const View = forwardRef<HTMLDivElement, ViewProps>(({
   if (borderWidth !== undefined) dynamicStyles.borderWidth = borderWidth;
   if (borderColor) dynamicStyles.borderColor = borderColor;
 
+  // Flatten style array to object (HTML divs don't support style arrays)
+  const flattenedStyle = useMemo(() => {
+    if (!style) return undefined;
+    if (Array.isArray(style)) {
+      return StyleSheet.flatten(style);
+    }
+    return style;
+  }, [style]);
+
   /** @ts-ignore */
-  const webProps = getWebProps([viewStyles.view, dynamicStyles, style as any]);
+  const webProps = getWebProps([(viewStyles.view as any)({}), dynamicStyles]);
 
   const mergedRef = useMergeRefs(ref, webProps.ref);
 
   return (
     <div
+      style={flattenedStyle as any}
       {...webProps}
       ref={mergedRef}
       id={id}

package/src/extensions/applyExtension.ts

@@ -0,0 +1,210 @@
+import { deepMerge } from '../utils/deepMerge';
+import { Styles, ElementStyle, ComponentName } from './types';
+import { getExtension, getReplacement } from './extendComponent';
+import { Theme } from '@idealyst/theme';
+
+/**
+ * Wrap a dynamic style function to merge with extension styles.
+ *
+ * All styles in Unistyles must be dynamic functions (not static objects)
+ * to avoid Babel transform issues. This utility wraps a style function
+ * to automatically merge extension styles when the function is called.
+ *
+ * @param styleFn - The original dynamic style function
+ * @param elementExtension - Extension styles for this element (can be undefined).
+ *        Can be either a static styles object or a function (props) => styles
+ *        for prop-aware extensions.
+ * @returns A new function that returns merged styles
+ *
+ * @example
+ * ```typescript
+ * import { withExtension } from '../extensions/applyExtension';
+ * import { getExtension } from '../extensions/extendComponent';
+ *
+ * export const buttonStyles = StyleSheet.create((theme: Theme) => {
+ *   const ext = getExtension('Button', theme);
+ *
+ *   return {
+ *     button: withExtension(createButtonStyles(theme), ext?.button),
+ *     text: withExtension(createTextStyles(theme), ext?.text),
+ *   };
+ * });
+ * ```
+ *
+ * @remarks
+ * - If no extension is provided, returns the original function unchanged
+ * - Extension styles take priority over base styles (deep merged)
+ * - Works with any style function signature
+ * - If extension is a function, it receives the same props as the base style function
+ */
+export function withExtension<TProps, TResult extends Styles>(
+    styleFn: (props: TProps) => TResult,
+    elementExtension: Styles | ((props: TProps) => Styles) | undefined
+): (props: TProps) => TResult {
+    // If no extension, return original function unchanged
+    if (!elementExtension) {
+        return styleFn;
+    }
+
+    // Return wrapped function that merges extension
+    return (props: TProps): TResult => {
+        const baseStyles = styleFn(props);
+        // If extension is a function, call it with props; otherwise use as-is
+        const extStyles = typeof elementExtension === 'function'
+            ? elementExtension(props)
+            : elementExtension;
+        return deepMerge(baseStyles, extStyles) as TResult;
+    };
+}
+
+/**
+ * Wrap a parameterless style function with extension.
+ *
+ * Use this for style functions that don't take any parameters.
+ * This is common for simpler elements like iconContainer.
+ *
+ * @param styleFn - The original style function (no parameters)
+ * @param elementExtension - Extension styles for this element
+ * @returns A new function that returns merged styles
+ *
+ * @example
+ * ```typescript
+ * const createIconContainerStyles = (theme: Theme) => {
+ *   return () => ({
+ *     display: 'flex',
+ *     flexDirection: 'row',
+ *     gap: 4,
+ *   });
+ * };
+ *
+ * // In StyleSheet.create:
+ * iconContainer: withSimpleExtension(
+ *   createIconContainerStyles(theme),
+ *   ext?.iconContainer
+ * ),
+ * ```
+ */
+export function withSimpleExtension<TResult extends Styles>(
+    styleFn: () => TResult,
+    elementExtension: Styles | undefined
+): () => TResult {
+    if (!elementExtension) {
+        return styleFn;
+    }
+
+    return (): TResult => {
+        const baseStyles = styleFn();
+        return deepMerge(baseStyles, elementExtension) as TResult;
+    };
+}
+
+/**
+ * Normalize a style value (from replacement) into a dynamic function.
+ *
+ * Replacements can be either:
+ * - A function (props) => styles - used directly
+ * - A static styles object - wrapped in a function
+ *
+ * @param value - The replacement value (function or static object)
+ * @param defaultFn - Default function to use if value is undefined
+ * @returns The default function (type-safe) - replacement handling is done at runtime
+ *
+ * @example
+ * ```typescript
+ * const replacement = getReplacement('Button', theme);
+ *
+ * // If replacement.button is a function, use it directly
+ * // If replacement.button is an object, wrap it in () => replacement.button
+ * // If undefined, use createButtonStyles(theme)
+ * button: withExtension(
+ *   normalizeStyleFn(replacement?.button, createButtonStyles(theme)),
+ *   ext?.button
+ * ),
+ * ```
+ */
+export function normalizeStyleFn<TProps, TResult>(
+    value: unknown,
+    defaultFn: (props: TProps) => TResult
+): (props: TProps) => TResult {
+    if (value === undefined || value === null) {
+        return defaultFn;
+    }
+    if (typeof value === 'function') {
+        return value as (props: TProps) => TResult;
+    }
+    // Static object - wrap in a function that ignores props
+    return (() => value) as (props: TProps) => TResult;
+}
+
+/**
+ * Normalize a simple style value (no props) into a parameterless function.
+ *
+ * @param value - The replacement value (function or static object)
+ * @param defaultFn - Default function to use if value is undefined
+ * @returns A parameterless function that returns styles
+ */
+export function normalizeSimpleStyleFn<TResult>(
+    value: unknown,
+    defaultFn: () => TResult
+): () => TResult {
+    if (value === undefined || value === null) {
+        return defaultFn;
+    }
+    if (typeof value === 'function') {
+        return value as () => TResult;
+    }
+    // Static object - wrap in a function
+    return (() => value) as () => TResult;
+}
+
+/**
+ * Apply extensions and replacements to a set of style creators.
+ *
+ * This is a simplified helper that handles the common pattern of:
+ * 1. Getting extensions and replacements for a component
+ * 2. Applying normalizeStyleFn for each element
+ * 3. Merging extensions on top
+ *
+ * @param component - The component name
+ * @param theme - The current theme
+ * @param styleCreators - Object mapping element names to their style creator functions
+ * @returns Object with the same keys, but with extensions/replacements applied
+ *
+ * @example
+ * ```typescript
+ * export const buttonStyles = StyleSheet.create((theme: Theme) => {
+ *     return applyExtensions('Button', theme, {
+ *         button: createButtonStyles(theme),
+ *         text: createTextStyles(theme),
+ *         icon: createIconStyles(theme),
+ *     });
+ * });
+ * ```
+ */
+export function applyExtensions<
+    K extends ComponentName,
+    T extends Record<string, ((...args: any[]) => any)>
+>(
+    component: K,
+    theme: Theme,
+    styleCreators: T
+): T {
+    const ext = getExtension(component, theme);
+    const replacement = getReplacement(component, theme);
+
+    const result = {} as T;
+
+    for (const key in styleCreators) {
+        const creator = styleCreators[key];
+        const elementExt = ext?.[key as string as keyof typeof ext] as ElementStyle | undefined;
+        const elementReplacement = replacement?.[key as string as keyof typeof replacement];
+
+        // Apply replacement (if any) then extension (if any)
+        result[key] = withExtension(
+            normalizeStyleFn(elementReplacement, creator),
+            elementExt
+        ) as T[typeof key];
+    }
+
+    return result;
+}

package/src/extensions/extendComponent.ts

@@ -0,0 +1,377 @@
+import { Theme } from '@idealyst/theme';
+import {
+    ComponentStyleElements,
+    ComponentName,
+    StyleExtension,
+} from './types';
+import { deepMergeAll } from '../utils/deepMerge';
+
+/**
+ * Registry storing style extensions for each component.
+ * Key is the component name, value is an array of extensions (applied in order).
+ */
+const extensionRegistry = new Map<ComponentName, StyleExtension<any>[]>();
+
+/**
+ * Registry storing complete style replacements for each component.
+ * When set, the replacement is used instead of base styles + extensions.
+ */
+const replacementRegistry = new Map<ComponentName, StyleExtension<any>>();
+
+/**
+ * Completely replace the styles of a component.
+ *
+ * Unlike `extendComponent` which merges with base styles, `replaceStyles`
+ * completely overrides the default stylesheet. Extensions are NOT applied
+ * when a replacement is set.
+ *
+ * **Use with caution:** You're responsible for providing all necessary styles,
+ * including variant styles, platform-specific styles, and accessibility states.
+ *
+ * @param component - The component name to replace styles for
+ * @param replacement - Complete style replacement, either as an object or a function receiving theme
+ *
+ * @example Complete replacement with theme access
+ * ```typescript
+ * import { replaceStyles } from '@idealyst/components';
+ *
+ * replaceStyles('Button', (theme) => ({
+ *   button: {
+ *     backgroundColor: theme.colors.surface.primary,
+ *     borderRadius: 0,
+ *     padding: 16,
+ *     variants: {
+ *       size: {
+ *         sm: { padding: 8 },
+ *         md: { padding: 16 },
+ *         lg: { padding: 24 },
+ *       },
+ *     },
+ *   },
+ *   text: {
+ *     color: theme.colors.text.primary,
+ *     fontSize: 16,
+ *   },
+ *   icon: {
+ *     width: 20,
+ *     height: 20,
+ *   },
+ *   iconContainer: {
+ *     display: 'flex',
+ *     alignItems: 'center',
+ *   },
+ * }));
+ * ```
+ *
+ * @example Clear replacement to restore defaults
+ * ```typescript
+ * clearReplacement('Button');
+ * ```
+ */
+export function replaceStyles<K extends ComponentName>(
+    component: K,
+    replacement: StyleExtension<ComponentStyleElements[K]>
+): void {
+    replacementRegistry.set(component, replacement);
+}
+
+/**
+ * Get the replacement styles for a component, if set.
+ *
+ * @param component - The component name
+ * @param theme - The current theme (used if replacement is a function)
+ * @returns The resolved replacement styles, or undefined if none set
+ *
+ * @internal
+ */
+export function getReplacement<K extends ComponentName>(
+    component: K,
+    theme: Theme
+): Partial<ComponentStyleElements[K]> | undefined {
+    const replacement = replacementRegistry.get(component);
+    if (!replacement) {
+        return undefined;
+    }
+    return typeof replacement === 'function' ? replacement(theme) : replacement;
+}
+
+/**
+ * Clear the style replacement for a specific component.
+ * After clearing, the component will use base styles + extensions again.
+ *
+ * @param component - The component name to clear replacement for
+ *
+ * @example
+ * ```typescript
+ * import { clearReplacement } from '@idealyst/components';
+ *
+ * clearReplacement('Button');
+ * ```
+ */
+export function clearReplacement<K extends ComponentName>(component: K): void {
+    replacementRegistry.delete(component);
+}
+
+/**
+ * Clear all style replacements.
+ *
+ * @example
+ * ```typescript
+ * import { clearAllReplacements } from '@idealyst/components';
+ *
+ * clearAllReplacements();
+ * ```
+ */
+export function clearAllReplacements(): void {
+    replacementRegistry.clear();
+}
+
+/**
+ * Check if a component has a style replacement set.
+ *
+ * @param component - The component name to check
+ * @returns true if the component has a replacement set
+ *
+ * @example
+ * ```typescript
+ * import { hasReplacement } from '@idealyst/components';
+ *
+ * if (hasReplacement('Button')) {
+ *   console.log('Button styles are completely replaced');
+ * }
+ * ```
+ */
+export function hasReplacement<K extends ComponentName>(component: K): boolean {
+    return replacementRegistry.has(component);
+}
+
+/**
+ * Globally extend the styles of a component.
+ *
+ * Extensions affect ALL instances of that component app-wide.
+ * Extensions are merged with base styles - extension styles win on conflict.
+ *
+ * **Precedence rules:**
+ * - Extensions override base component styles
+ * - Later extensions override earlier extensions
+ * - Setting a value to `undefined` removes that style property
+ * - Nested objects (like `_web`, `variants`) are deep merged
+ *
+ * @param component - The component name to extend (e.g., 'Button', 'Card')
+ * @param extension - Style overrides, either as an object or a function receiving theme
+ *
+ * @example Static extension
+ * ```typescript
+ * import { extendComponent } from '@idealyst/components';
+ *
+ * extendComponent('Button', {
+ *   button: {
+ *     borderRadius: 20,
+ *     shadowColor: '#000',
+ *     shadowOffset: { width: 0, height: 2 },
+ *     shadowOpacity: 0.25,
+ *     shadowRadius: 4,
+ *   },
+ *   text: {
+ *     textTransform: 'uppercase',
+ *     letterSpacing: 1,
+ *   },
+ * });
+ * ```
+ *
+ * @example Theme-aware extension
+ * ```typescript
+ * extendComponent('Button', (theme) => ({
+ *   button: {
+ *     ...theme.shadows.lg,
+ *     backgroundColor: theme.colors.surface.secondary,
+ *   },
+ *   text: {
+ *     color: theme.colors.text.primary,
+ *   },
+ * }));
+ * ```
+ *
+ * @example Multiple extensions (later ones have higher precedence)
+ * ```typescript
+ * // Base brand styles
+ * extendComponent('Button', {
+ *   button: { borderRadius: 8 },
+ * });
+ *
+ * // Feature-specific override (wins over base)
+ * extendComponent('Button', {
+ *   button: { borderRadius: 20 },
+ * });
+ * // Result: borderRadius is 20
+ * ```
+ *
+ * @example Removing a style property
+ * ```typescript
+ * extendComponent('Button', {
+ *   button: {
+ *     shadowColor: undefined,  // Removes shadowColor
+ *     shadowOpacity: undefined, // Removes shadowOpacity
+ *   },
+ * });
+ * ```
+ *
+ * @example Web-specific styles
+ * ```typescript
+ * extendComponent('Button', {
+ *   button: {
+ *     _web: {
+ *       cursor: 'pointer',
+ *       transition: 'all 0.2s ease',
+ *       _hover: {
+ *         transform: 'scale(1.02)',
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+// Overload for static object extension
+export function extendComponent<K extends ComponentName>(
+    component: K,
+    extension: Partial<ComponentStyleElements[K]>
+): void;
+// Overload for theme-aware function extension
+export function extendComponent<K extends ComponentName>(
+    component: K,
+    extension: (theme: Theme) => Partial<ComponentStyleElements[K]>
+): void;
+// Implementation
+export function extendComponent<K extends ComponentName>(
+    component: K,
+    extension: StyleExtension<ComponentStyleElements[K]>
+): void {
+    const existing = extensionRegistry.get(component) ?? [];
+    existing.push(extension);
+    extensionRegistry.set(component, existing);
+}
+
+/**
+ * Get the resolved extension for a component.
+ *
+ * This is an internal function used by component stylesheets to retrieve
+ * and apply extensions. All registered extensions are merged in order,
+ * with later extensions taking precedence.
+ *
+ * @param component - The component name
+ * @param theme - The current theme (used if extension is a function)
+ * @returns The resolved merged extension styles, or undefined if none registered
+ *
+ * @internal
+ */
+export function getExtension<K extends ComponentName>(
+    component: K,
+    theme: Theme
+): Partial<ComponentStyleElements[K]> | undefined {
+    const extensions = extensionRegistry.get(component);
+
+    if (!extensions || extensions.length === 0) {
+        return undefined;
+    }
+
+    // Resolve all extensions (call functions with theme)
+    const resolved = extensions.map(ext =>
+        typeof ext === 'function' ? ext(theme) : ext
+    );
+
+    // Merge all extensions in order (later ones win)
+    return deepMergeAll(...resolved) as Partial<ComponentStyleElements[K]>;
+}
+
+/**
+ * Clear all extensions for a specific component.
+ *
+ * @param component - The component name to clear extensions for
+ *
+ * @example
+ * ```typescript
+ * import { clearExtension } from '@idealyst/components';
+ *
+ * // Remove all Button extensions
+ * clearExtension('Button');
+ * ```
+ */
+export function clearExtension<K extends ComponentName>(component: K): void {
+    extensionRegistry.delete(component);
+}
+
+/**
+ * Clear all component extensions.
+ *
+ * @example
+ * ```typescript
+ * import { clearAllExtensions } from '@idealyst/components';
+ *
+ * // Remove all component extensions
+ * clearAllExtensions();
+ * ```
+ */
+export function clearAllExtensions(): void {
+    extensionRegistry.clear();
+}
+
+/**
+ * Check if a component has any extensions registered.
+ *
+ * @param component - The component name to check
+ * @returns true if the component has at least one extension
+ *
+ * @example
+ * ```typescript
+ * import { hasExtension } from '@idealyst/components';
+ *
+ * if (hasExtension('Button')) {
+ *   console.log('Button has custom styles');
+ * }
+ * ```
+ */
+export function hasExtension<K extends ComponentName>(component: K): boolean {
+    const extensions = extensionRegistry.get(component);
+    return extensions !== undefined && extensions.length > 0;
+}
+
+/**
+ * Get all registered component extensions.
+ * Useful for debugging or inspecting what extensions are active.
+ *
+ * @returns Array of component names that have extensions
+ *
+ * @example
+ * ```typescript
+ * import { getExtendedComponents } from '@idealyst/components';
+ *
+ * const extended = getExtendedComponents();
+ * console.log('Extended components:', extended);
+ * // ['Button', 'Card', 'Input']
+ * ```
+ */
+export function getExtendedComponents(): ComponentName[] {
+    return Array.from(extensionRegistry.keys()).filter(key => {
+        const extensions = extensionRegistry.get(key);
+        return extensions && extensions.length > 0;
+    });
+}
+
+/**
+ * Get the number of extensions registered for a component.
+ * Useful for debugging.
+ *
+ * @param component - The component name
+ * @returns Number of extensions registered
+ *
+ * @example
+ * ```typescript
+ * import { getExtensionCount } from '@idealyst/components';
+ *
+ * console.log('Button extensions:', getExtensionCount('Button'));
+ * // 3
+ * ```
+ */
+export function getExtensionCount<K extends ComponentName>(component: K): number {
+    return extensionRegistry.get(component)?.length ?? 0;
+}