@react-hive/honey-style 6.2.0 → 7.0.0

package/dist/styled.d.ts

@@ -1,15 +1,76 @@
-import type { ComponentProps, ComponentPropsWithRef, ElementType, ReactElement } from 'react';
-import type { FastOmit, HoneyHtmlDataAttributes, HoneyStyledContext, HoneyStyledInterpolation, HoneyStyledPropsWithAs, Nullable, Override } from './types';
+import type { ComponentProps, ElementType, ReactElement } from 'react';
+import type { FastOmit, HoneyStyledContext, HoneyStyledInterpolation, HoneyStyledPropsWithAs, Override } from './types';
 import { HONEY_STYLED_COMPONENT_ID_PROP } from './constants';
-export type HoneyStyledProps<Element extends ElementType, Props extends object> = HoneyStyledPropsWithAs<Element, HoneyHtmlDataAttributes & ComponentPropsWithRef<Element> & Props>;
-type DefaultPropsResolver<Target extends ElementType, DefaultProps extends object, Props extends object, CombinedProps extends object = Override<DefaultProps, Props>> = HoneyStyledPropsWithAs<Target, FastOmit<Partial<CombinedProps>, 'as'>> | ((props: HoneyStyledContext<HoneyStyledPropsWithAs<Target, CombinedProps>>) => HoneyStyledPropsWithAs<Target, FastOmit<Partial<CombinedProps>, 'as'>>);
-type HoneyStyledPublicComponentProps<AsElement extends ElementType, Props extends object> = HoneyStyledPropsWithAs<AsElement, Override<ComponentProps<AsElement>, FastOmit<Props, 'as'>>>;
-type HoneyStyledComponent<OverrideTarget extends ElementType, Props extends object> = (<AsElement extends ElementType = OverrideTarget>(props: HoneyStyledPublicComponentProps<AsElement, Props>) => Nullable<ReactElement<Props>>) & {
+type DefaultPropsResolver<Target extends ElementType, DefaultProps extends object, Props extends object, CombinedProps extends object = FastOmit<Override<DefaultProps, Props>, 'as'>> = HoneyStyledPropsWithAs<Target, Partial<CombinedProps>> | ((props: HoneyStyledContext<HoneyStyledPropsWithAs<Target, CombinedProps>>) => HoneyStyledPropsWithAs<Target, Partial<CombinedProps>>);
+type HoneyStyledPublicComponentProps<AsElement extends ElementType, Props extends object> = HoneyStyledPropsWithAs<AsElement, Override<ComponentProps<AsElement>, Props>>;
+type HoneyStyledComponent<OverrideTarget extends ElementType, Props extends object> = (<AsElement extends ElementType = OverrideTarget>(props: HoneyStyledPublicComponentProps<AsElement, FastOmit<Props, 'as'>>) => ReactElement<Props>) & {
     [HONEY_STYLED_COMPONENT_ID_PROP]: string;
     displayName?: string;
 };
 interface StyledOptions {
-    omitProps?: (name: string) => boolean;
+    /**
+     * Determines whether a prop should be removed before being forwarded
+     * to the rendered element.
+     *
+     * @param propName - The prop name to check.
+     *
+     * @returns Returns true if the prop should be omitted.
+     */
+    omitProps?: (propName: string) => boolean;
 }
+/**
+ * Creates a Honey-styled component from an HTML element or React component.
+ *
+ * The returned function accepts a tagged template literal with static CSS and dynamic
+ * interpolations. Interpolations receive the resolved styled context, including the
+ * current theme, default props, and props passed to the component.
+ *
+ * The generated component supports the polymorphic `as` prop, so the rendered element
+ * can be changed while preserving the native props of the selected element.
+ *
+ * Default props can be provided as either an object or a resolver function. Props passed
+ * directly to the rendered styled component override default props.
+ *
+ * @template TargetProps - The custom props available to style interpolations.
+ * @template Target - The base HTML element or React component used for rendering.
+ * @template OverrideTarget - The default polymorphic element used for public prop inference.
+ *
+ * @param target - The base HTML element or React component to style.
+ * @param defaultProps - Optional default props or a function that resolves default props from context.
+ * @param options - Optional styled component options.
+ *
+ * @returns A tagged template function that creates a styled component.
+ *
+ * @example
+ * ```tsx
+ * const Box = styled('div')`
+ *   color: red;
+ * `;
+ *
+ * <Box data-testid="box">Content</Box>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const Button = styled<{ variant: 'primary' | 'secondary' }, 'button'>('button')`
+ *   ${({ variant }) => css`
+ *     color: ${variant === 'primary' ? 'white' : 'black'};
+ *   `}
+ * `;
+ *
+ * <Button variant="primary" type="button" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const LinkBox = styled('div')`
+ *   color: blue;
+ * `;
+ *
+ * <LinkBox as="a" href="https://example.com">
+ *   Link
+ * </LinkBox>
+ * ```
+ */
 export declare const styled: <TargetProps extends object, Target extends ElementType = ElementType, OverrideTarget extends ElementType = Target>(target: Target, defaultProps?: DefaultPropsResolver<OverrideTarget, ComponentProps<OverrideTarget>, TargetProps>, { omitProps }?: StyledOptions) => <Props extends object = TargetProps>(strings: TemplateStringsArray, ...interpolations: HoneyStyledInterpolation<Override<ComponentProps<OverrideTarget>, Props>>[]) => HoneyStyledComponent<OverrideTarget, Props>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-hive/honey-style",
-  "version": "6.2.0",
+  "version": "7.0.0",
   "description": "",
   "keywords": [
     "react",