@fluentui/react-utilities 0.0.0-nightlyd3bf09bf8120211201.1 → 0.0.0-nightlyd45ba4664620220211.1

package/dist/react-utilities.d.ts

@@ -11,7 +11,7 @@ export declare const anchorProperties: Record<string, number>;
 /**
  * Apply the trigger props to the children, either by calling the render function, or cloning with the new props.
  */
-export declare const applyTriggerPropsToChildren: <TTriggerProps>(children: React_2.ReactElement<any, string | ((props: any) => React_2.ReactElement<any, string | any | (new (props: any) => React_2.Component<any, any, any>)> | null) | (new (props: any) => React_2.Component<any, any, any>)> | ((props: TTriggerProps) => React_2.ReactNode) | null | undefined, triggerProps: TTriggerProps) => React_2.ReactNode;
+export declare const applyTriggerPropsToChildren: <TTriggerProps>(children: React_2.ReactElement<any, string | React_2.JSXElementConstructor<any>> | ((props: TTriggerProps) => React_2.ReactElement | null) | null | undefined, triggerProps: TTriggerProps) => React_2.ReactElement | null;
 
 /**
  * Helper type for inferring the type of the as prop from a Props type.
@@ -58,8 +58,6 @@ export declare const buttonProperties: Record<string, number>;
  */
 export declare function canUseDOM(): boolean;
 
-export declare type ChangeCallback<TElement extends HTMLElement, TValue, TEvent extends React_2.SyntheticEvent<TElement> | undefined> = (ev: TEvent, newValue: TValue | undefined) => void;
-
 /**
  * Clamps `value` to a number between the min and max.
  *
@@ -73,25 +71,22 @@ export declare const colGroupProperties: Record<string, number>;
 
 export declare const colProperties: Record<string, number>;
 
-export declare type ComponentProps<Shorthands extends ObjectShorthandPropsRecord, Primary extends keyof Shorthands = 'root'> = Omit<{
-    [Key in keyof Shorthands]?: ShorthandProps<NonNullable<Shorthands[Key]>>;
-}, Primary & 'root'> & PropsWithoutRef<Shorthands[Primary]>;
-
-export declare type ComponentState<Shorthands extends ObjectShorthandPropsRecord> = {
-    components?: {
-        [Key in keyof Shorthands]-?: React_2.ComponentType<NonNullable<Shorthands[Key]> extends ObjectShorthandProps<infer P> ? P : NonNullable<Shorthands[Key]>> | (NonNullable<Shorthands[Key]> extends AsIntrinsicElement<infer As> ? As : keyof JSX.IntrinsicElements);
-    };
-} & Shorthands;
+/**
+ * Defines the Props type for a component given its slots and the definition of which one is the primary slot,
+ * defaulting to root if one is not provided.
+ */
+export declare type ComponentProps<Slots extends SlotPropsRecord, Primary extends keyof Slots = 'root'> = Omit<Slots, Primary & 'root'> & PropsWithoutRef<ExtractSlotProps<Slots[Primary]>>;
 
 /**
- * Matches any shorthand props type.
- *
- * This should ONLY be used in type templates as in `extends DefaultObjectShorthandProps`;
- * it shouldn't be used as the type of a slot.
+ * Defines the State object of a component given its slots.
  */
-export declare type DefaultObjectShorthandProps = ObjectShorthandProps<Pick<React_2.HTMLAttributes<HTMLElement>, 'children' | 'className' | 'style'> & {
-    as?: keyof JSX.IntrinsicElements;
-}>;
+export declare type ComponentState<Slots extends SlotPropsRecord> = {
+    components: {
+        [Key in keyof Slots]-?: React_2.ComponentType<ExtractSlotProps<Slots[Key]>> | (ExtractSlotProps<Slots[Key]> extends AsIntrinsicElement<infer As> ? As : keyof JSX.IntrinsicElements);
+    };
+} & {
+    [Key in keyof Slots]: ReplaceNullWithUndefined<Exclude<Slots[Key], SlotShorthandValue | (Key extends 'root' ? null : never)>>;
+};
 
 /**
  * Default context value to use in case there is no SSRProvider. This is fine for client-only apps.
@@ -100,11 +95,6 @@ export declare type DefaultObjectShorthandProps = ObjectShorthandProps<Pick<Reac
  */
 export declare const defaultSSRContextValue: SSRContextValue;
 
-/**
- * Default value can be a value or an initializer
- */
-declare type DefaultValue<TValue> = TValue | (() => TValue);
-
 /**
  * An array of DIV tag properties and events.
  *
@@ -112,6 +102,35 @@ declare type DefaultValue<TValue> = TValue | (() => TValue);
  */
 export declare const divProperties: Record<string, number>;
 
+/**
+ * HTML element types that are not allowed to have children.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Glossary/Empty_element
+ */
+declare type EmptyIntrisicElements = 'area' | 'base' | 'br' | 'col' | 'embed' | 'hr' | 'img' | 'input' | 'link' | 'meta' | 'param' | 'source' | 'track' | 'wbr';
+
+/**
+ * Removes SlotShorthandValue and null from the slot type, extracting just the slot's Props object.
+ */
+export declare type ExtractSlotProps<S> = Exclude<S, SlotShorthandValue | null | undefined>;
+
+/**
+ * Allows a component to be tagged as a FluentUI trigger component.
+ *
+ * Triggers are special-case components: they attach event listeners and other props on their child,
+ * and use them to trigger another component to show. Examples include `MenuTrigger` and `Tooltip`.
+ *
+ * A component can be tagged as a trigger as follows:
+ * ```ts
+ * const MyComponent: React.FC<MyComponentProps> & FluentTriggerComponent = ...;
+ *
+ * MyComponent.isFluentTriggerComponent = true; // MUST also set this to true
+ * ```
+ */
+export declare type FluentTriggerComponent = {
+    isFluentTriggerComponent?: boolean;
+};
+
 /**
  * An array of FORM tag properties and events.
  *
@@ -157,19 +176,19 @@ export declare function getNativeProps<T extends Record<string, any>>(props: Rec
  *
  * @returns An object containing the native props for the `root` and primary slots.
  */
-export declare const getPartitionedNativeProps: ({ primarySlotTagName, props, excludedPropNames, }: {
+export declare const getPartitionedNativeProps: <Props extends Pick<React_2.HTMLAttributes<HTMLElement>, "style" | "className">, ExcludedPropKeys extends Extract<keyof Props, string> = never>({ primarySlotTagName, props, excludedPropNames, }: {
     /** The primary slot's element type (e.g. 'div') */
     primarySlotTagName: keyof JSX.IntrinsicElements;
     /** The component's props object */
-    props: Pick<React_2.HTMLAttributes<HTMLElement>, 'style' | 'className'>;
+    props: Props;
     /** List of native props to exclude from the returned value */
-    excludedPropNames?: string[] | undefined;
+    excludedPropNames?: ExcludedPropKeys[] | undefined;
 }) => {
     root: {
         style: React_2.CSSProperties | undefined;
         className: string | undefined;
     };
-    primary: React_2.HTMLAttributes<any>;
+    primary: Omit<Props, ExcludedPropKeys>;
 };
 
 /**
@@ -186,16 +205,39 @@ export declare const getRTLSafeKey: (key: string, dir: 'ltr' | 'rtl') => string;
  * Slots will render as null if they are rendered as primitives with undefined children.
  *
  * The slotProps will always omit the `as` prop within them, and for slots that are string
- * primitives, the props will be filtered according the the slot type. For example, if the
- * slot is rendered `as: 'a'`, the props will be filtered for acceptable anchor props.
+ * primitives, the props will be filtered according to the slot type by the type system.
+ * For example, if the slot is rendered `as: 'a'`, the props will be filtered for acceptable
+ * anchor props. Note that this is only enforced at build time by Typescript -- there is no
+ * runtime code filtering props in this function.
  *
  * @param state - State including slot definitions
- * @param slotNames - Name of which props are slots
  * @returns An object containing the `slots` map and `slotProps` map.
  */
-export declare function getSlots<R extends ObjectShorthandPropsRecord>(state: ComponentState<R>, slotNames?: (keyof R)[]): {
+export declare function getSlots<R extends SlotPropsRecord>(state: ComponentState<R>): {
     slots: Slots<R>;
-    slotProps: SlotProps<R>;
+    slotProps: ObjectSlotProps<R>;
+};
+
+/**
+ * Gets the trigger element of a FluentTriggerComponent (such as Tooltip or MenuTrigger).
+ *
+ * In the case where the immediate child is itself a FluentTriggerComponent and/or React Fragment,
+ * it returns the first descendant that is _not_ a FluentTriggerComponent or Fragment.
+ * This allows multiple triggers to be stacked, and still apply their props to the actual trigger element.
+ *
+ * For example, the following returns `<div id="child" />`:
+ * ```jsx
+ * getTriggerChild(
+ *   <Tooltip>
+ *     <MenuTrigger>
+ *       <div id="child" />
+ *     </MenuTrigger>
+ *   </Tooltip>
+ * );
+ * ```
+ */
+export declare const getTriggerChild: (children: React_2.ReactNode) => React_2.ReactElement & {
+    ref?: React_2.Ref<unknown>;
 };
 
 /**
@@ -232,25 +274,19 @@ export declare const imgProperties: Record<string, number>;
 export declare const inputProperties: Record<string, number>;
 
 /**
- * Define the slot arguments for a slot that supports one or more intrinsic element types, such as 'div'.
- * For slots that support custom components, use {@link ObjectShorthandProps} instead.
- *
- * The first param is the slot's default type if no `as` prop is specified.
- * The second param is an optional union of alternative types that can be specified for the `as` prop.
- *
- * ```
- * IntrinsicShorthandProps<'div'> // Slot is always div
- * IntrinsicShorthandProps<'button', 'a'> // Defaults to button, but allows as="a" with anchor-specific props
- * IntrinsicShorthandProps<'label', 'span' | 'div'>; // Defaults to label, but allows as="span" or as="div"
- * ```
+ * Helper type for {@link Slot}. Modifies `JSX.IntrinsicElements[Type]`:
+ * * Removes legacy string ref.
+ * * Disallows children for empty tags like 'img'.
  */
-export declare type IntrinsicShorthandProps<DefaultAs extends keyof JSX.IntrinsicElements, AlternateAs extends keyof JSX.IntrinsicElements = never> = IsSingleton<DefaultAs> extends false ? 'Error: first parameter to IntrinsicShorthandProps must be a single element type, not a union of types' : ({
-    as?: DefaultAs;
-} & ObjectShorthandProps<React_2.PropsWithRef<JSX.IntrinsicElements[DefaultAs]>>) | {
-    [As in AlternateAs]: {
-        as: As;
-    } & ObjectShorthandProps<React_2.PropsWithRef<JSX.IntrinsicElements[As]>>;
-}[AlternateAs];
+declare type IntrisicElementProps<Type extends keyof JSX.IntrinsicElements> = React_2.PropsWithRef<JSX.IntrinsicElements[Type]> & (Type extends EmptyIntrisicElements ? {
+    children?: never;
+} : {});
+
+/**
+ * Checks if a given element is a FluentUI trigger (e.g. `MenuTrigger` or `Tooltip`).
+ * See the {@link FluentTriggerComponent} type for more info.
+ */
+export declare const isFluentTrigger: (element: React_2.ReactElement) => boolean | undefined;
 
 /**
  * Evaluates to true if the given type contains exactly one string, or false if it is a union of strings.
@@ -278,24 +314,10 @@ export declare const labelProperties: Record<string, number>;
  */
 export declare const liProperties: Record<string, number>;
 
-/**
- * Simple constant function for returning null, used to render empty templates in JSX.
- */
-export declare const nullRender: () => null;
-
-/**
- * Defines the slot props for a slot that supports a Component type.
- *
- * For intrinsic elements like 'div', use {@link IntrinsicShorthandProps} instead.
- */
-export declare type ObjectShorthandProps<Props extends {
-    children?: React_2.ReactNode;
-} = {}> = Props & {
-    children?: Props['children'] | ShorthandRenderFunction<Props>;
+declare type ObjectSlotProps<S extends SlotPropsRecord> = {
+    [K in keyof S]-?: ExtractSlotProps<S[K]> extends AsIntrinsicElement<infer As> ? UnionToIntersection<JSX.IntrinsicElements[As]> : ExtractSlotProps<S[K]> extends React_2.ComponentType<infer P> ? P : never;
 };
 
-export declare type ObjectShorthandPropsRecord = Record<string, DefaultObjectShorthandProps | undefined>;
-
 /**
  * This is part of a hack to infer the element type from a native element *props* type.
  * The only place the original element is found in a native props type (at least that's workable
@@ -332,16 +354,11 @@ export declare const olProperties: Record<string, number>;
  */
 export declare function omit<TObj extends Record<string, any>, Exclusions extends (keyof TObj)[]>(obj: TObj, exclusions: Exclusions): Omit<TObj, Exclusions[number]>;
 
-/**
- * Similar to React.Children.only, but drills into fragments rather than treating them as a single child
- */
-export declare const onlyChild: <P>(child: string | number | boolean | {} | React_2.ReactNodeArray | React_2.ReactPortal | React_2.ReactElement<P, string | ((props: any) => React_2.ReactElement<any, string | any | (new (props: any) => React_2.Component<any, any, any>)> | null) | (new (props: any) => React_2.Component<any, any, any>)> | null | undefined) => React_2.ReactElement<P, string | ((props: any) => React_2.ReactElement<any, string | any | (new (props: any) => React_2.Component<any, any, any>)> | null) | (new (props: any) => React_2.Component<any, any, any>)>;
-
 export declare const optionProperties: Record<string, number>;
 
 /**
  * Removes the 'ref' prop from the given Props type, leaving unions intact (such as the discriminated union created by
- * IntrinsicShorthandProps). This allows IntrinsicShorthandProps to be used with React.forwardRef.
+ * IntrinsicSlotProps). This allows IntrinsicSlotProps to be used with React.forwardRef.
  *
  * The conditional "extends unknown" (always true) exploits a quirk in the way TypeScript handles conditional
  * types, to prevent unions from being expanded.
@@ -354,6 +371,11 @@ export declare type PropsWithoutRef<P> = 'ref' extends keyof P ? (P extends unkn
  */
 export declare type RefObjectFunction<T> = React_2.RefObject<T> & ((value: T) => void);
 
+/**
+ * If type T includes `null`, remove it and add `undefined` instead.
+ */
+export declare type ReplaceNullWithUndefined<T> = T extends null ? Exclude<T, null> | undefined : T;
+
 /**
  * Resets generated IDs, should be used only in tests.
  *
@@ -362,14 +384,19 @@ export declare type RefObjectFunction<T> = React_2.RefObject<T> & ((value: T) =>
 export declare function resetIdsForTests(): void;
 
 /**
- * Resolves ShorthandProps into ObjectShorthandProps, to ensure normalization of the signature
+ * Resolves shorthands into slot props, to ensure normalization of the signature
  * being passed down to getSlots method
- * @param value - the base ShorthandProps
- * @param options - options to resolve ShorthandProps
+ * @param value - the base shorthand props
+ * @param options - options to resolve shorthand props
  */
-export declare function resolveShorthand<Props extends DefaultObjectShorthandProps, Required extends boolean = false>(value: ShorthandProps<Props>, options?: ResolveShorthandOptions<Props, Required>): Required extends false ? Props | undefined : Props;
+export declare const resolveShorthand: ResolveShorthandFunction;
+
+export declare type ResolveShorthandFunction<Props extends UnknownSlotProps = UnknownSlotProps> = {
+    <P extends Props | null>(value: P | SlotShorthandValue | undefined, options?: ResolveShorthandOptions<P, true>): ReplaceNullWithUndefined<P>;
+    <P extends Props | null>(value: P | SlotShorthandValue | undefined, options?: ResolveShorthandOptions<P, boolean>): ReplaceNullWithUndefined<P> | undefined;
+};
 
-export declare type ResolveShorthandOptions<Props extends Record<string, any>, Required extends boolean = false> = {
+export declare type ResolveShorthandOptions<Props, Required extends boolean = false> = {
     required?: Required;
     defaultProps?: Props;
 };
@@ -381,10 +408,6 @@ export declare type ResolveShorthandOptions<Props extends Record<string, any>, R
  */
 export declare const selectProperties: Record<string, number>;
 
-export declare type ShorthandProps<Props extends DefaultObjectShorthandProps> = React_2.ReactChild | React_2.ReactNodeArray | React_2.ReactPortal | number | null | undefined | Props;
-
-export declare type ShorthandRenderFunction<Props> = (Component: React_2.ElementType<Props>, props: Omit<Props, 'children' | 'as'>) => React_2.ReactNode;
-
 /**
  * Checks if the keyboard event should preventDefault() for Enter and Spacebar keys
  *
@@ -392,14 +415,55 @@ export declare type ShorthandRenderFunction<Props> = (Component: React_2.Element
  */
 export declare function shouldPreventDefaultOnKeyDown(e: KeyboardEvent | React_2.KeyboardEvent): boolean;
 
-declare type SlotProps<S extends ObjectShorthandPropsRecord> = {
-    [K in keyof S]-?: NonNullable<S[K]> extends AsIntrinsicElement<infer As> ? UnionToIntersection<JSX.IntrinsicElements[As]> : NonNullable<S[K]> extends ObjectShorthandProps<infer P> ? P : never;
-};
+/**
+ * The props type and shorthand value for a slot. Type is either a single intrinsic element like `'div'`,
+ * or a component like `typeof Button`.
+ *
+ * If a slot needs to support multiple intrinsic element types, use the `AlternateAs` param (see examples below).
+ *
+ * By default, slots can be set to `null` to prevent them from being rendered. If a slot must always be rendered,
+ * wrap with `NonNullable` (see examples below).
+ *
+ * @example
+ * ```
+ * // Intrinsic element examples:
+ * Slot<'div'> // Slot is always div
+ * Slot<'button', 'a'> // Defaults to button, but allows as="a" with anchor-specific props
+ * Slot<'span', 'div' | 'pre'> // Defaults to span, but allows as="div" or as="pre"
+ * NonNullable<Slot<'div'>> // Slot that will always be rendered (can't be set to null by the user)
+ *
+ * // Component examples:
+ * Slot<typeof Button> // Slot is always a Button, and accepts all of Button's Props
+ * NonNullable<Slot<typeof Label>> // Slot is a Label and will always be rendered (can't be set to null by the user)
+ * ```
+ */
+export declare type Slot<Type extends keyof JSX.IntrinsicElements | React_2.ComponentType | UnknownSlotProps, AlternateAs extends keyof JSX.IntrinsicElements = never> = IsSingleton<Extract<Type, string>> extends true ? WithSlotShorthandValue<Type extends keyof JSX.IntrinsicElements ? {
+    as?: Type;
+} & WithSlotRenderFunction<IntrisicElementProps<Type>> : Type extends React_2.ComponentType<infer Props> ? WithSlotRenderFunction<Props> : Type> | {
+    [As in AlternateAs]: {
+        as: As;
+    } & WithSlotRenderFunction<IntrisicElementProps<As>>;
+}[AlternateAs] | null : 'Error: First parameter to Slot must not be not a union of types. See documentation of Slot type.';
+
+/**
+ * Matches any component's Slots type (such as ButtonSlots).
+ *
+ * This should ONLY be used in type templates as in `extends SlotPropsRecord`;
+ * it shouldn't be used as a component's Slots type.
+ */
+export declare type SlotPropsRecord = Record<string, UnknownSlotProps | SlotShorthandValue | null | undefined>;
+
+export declare type SlotRenderFunction<Props> = (Component: React_2.ElementType<Props>, props: Omit<Props, 'children' | 'as'>) => React_2.ReactNode;
 
-export declare type Slots<S extends ObjectShorthandPropsRecord> = {
-    [K in keyof S]-?: NonNullable<S[K]> extends AsIntrinsicElement<infer As> ? As : S[K] extends ObjectShorthandProps<infer P> ? React_2.ElementType<NonNullable<P>> : React_2.ElementType<NonNullable<S[K]>>;
+export declare type Slots<S extends SlotPropsRecord> = {
+    [K in keyof S]: ExtractSlotProps<S[K]> extends AsIntrinsicElement<infer As> ? As : ExtractSlotProps<S[K]> extends React_2.ComponentType<infer P> ? React_2.ElementType<NonNullable<P>> : React_2.ElementType<ExtractSlotProps<S[K]>>;
 };
 
+/**
+ * The shorthand value of a slot allows specifying its child
+ */
+export declare type SlotShorthandValue = React_2.ReactChild | React_2.ReactNodeArray | React_2.ReactPortal;
+
 export declare const SSRContext: React_2.Context<SSRContextValue>;
 
 /**
@@ -460,6 +524,16 @@ export declare const trProperties: Record<string, number>;
  */
 export declare type UnionToIntersection<U> = (U extends unknown ? (x: U) => U : never) extends (x: infer I) => U ? I : never;
 
+/**
+ * Matches any slot props type.
+ *
+ * This should ONLY be used in type templates as in `extends UnknownSlotProps`;
+ * it shouldn't be used as the type of a slot.
+ */
+export declare type UnknownSlotProps = Pick<React_2.HTMLAttributes<HTMLElement>, 'children' | 'className' | 'style'> & {
+    as?: keyof JSX.IntrinsicElements;
+};
+
 /**
  * Hook to store a value and generate callbacks for setting the value to true or false.
  * The identity of the callbacks will always stay the same.
@@ -493,42 +567,37 @@ export declare type UseBooleanCallbacks = {
 export declare function useConst<T>(initialValue: T | (() => T)): T;
 
 /**
- * A useState 'like' hook that allows optional user control
- * Useful for components which allow uncontrolled and controlled behaviour for users
- * @returns - https://reactjs.org/docs/hooks-state.html
+ * A `useState`-like hook to manage a value that could be either controlled or uncontrolled,
+ * such as a checked state or text input string.
+ *
+ * Unlike `setState`, it's okay to call the returned updater (dispatch) function for either a
+ * controlled or uncontrolled component. Calls will only be respected if the component is uncontrolled.
+ *
+ * @returns Same as [`useState`](https://reactjs.org/docs/hooks-reference.html#usestate): an array
+ * of the current value and an updater (dispatch) function. The updater function is referentially
+ * stable (won't change during the component's lifecycle). It can take either a new value, or a
+ * function which is passed the previous value and returns the new value. Unlike `setState`, calls
+ * to the updater function will only be respected if the component is uncontrolled.
+ * @see https://reactjs.org/docs/uncontrolled-components.html
  */
 export declare const useControllableState: <State>(options: UseControllableStateOptions<State>) => [State, React_2.Dispatch<React_2.SetStateAction<State>>];
 
 export declare type UseControllableStateOptions<State> = {
     /**
-     * User provided default state or factory initializer
+     * User-provided default state or initializer, for uncontrolled usage.
      */
     defaultState?: State | (() => State);
     /**
-     * User provided controllable state, undefined state means internal state will be used
+     * User-provided controlled state. `undefined` means internal state will be used.
      */
     state: State | undefined;
     /**
-     * Used to initialize state if all user provided states are undefined
+     * Used as the initial state if `state` and `defaultState` are both `undefined`.
+     * If `undefined` is the correct initial state, pass that here.
      */
     initialState: State;
 };
 
-/**
- * Hook to manage a value that could be either controlled or uncontrolled, such as a checked state or
- * text box string.
- * @param controlledValue - The controlled value passed in the props. This value will always be used if provided,
- * and the internal state will be updated to reflect it.
- * @param defaultUncontrolledValue - Initial value for the internal state in the uncontrolled case.
- * @returns An array of the current value and an updater callback. Like `React.useState`, the updater
- * callback always has the same identity, and it can take either a new value, or a function which
- * is passed the previous value and returns the new value.
- * @see https://reactjs.org/docs/uncontrolled-components.html
- */
-export declare function useControllableValue<TValue, TElement extends HTMLElement>(controlledValue: TValue, defaultUncontrolledValue: DefaultValue<TValue>): Readonly<[TValue, (update: React_2.SetStateAction<TValue>) => void]>;
-
-export declare function useControllableValue<TValue, TElement extends HTMLElement, TEvent extends React_2.SyntheticEvent<TElement> | undefined>(controlledValue: TValue, defaultUncontrolledValue: DefaultValue<TValue>, onChange: ChangeCallback<TElement, TValue, TEvent>): Readonly<[TValue, (update: React_2.SetStateAction<TValue>, ev?: React_2.FormEvent<TElement>) => void]>;
-
 /**
  * https://reactjs.org/docs/hooks-faq.html#how-to-read-an-often-changing-value-from-usecallback
  *
@@ -587,6 +656,25 @@ export declare const useIsomorphicLayoutEffect: typeof React_2.useEffect;
  */
 export declare function useIsSSR(): boolean;
 
+/**
+ * Combine two event callbacks into a single callback function that calls each one in order.
+ *
+ * This is useful to add an event listener to an existing element without overwriting the current listener, if any.
+ *
+ * For example:
+ * ```ts
+ * state.slot.onChange = useMergedCallbacks(state.slot.onChange, ev => {
+ *   // Handle onChange
+ * });
+ * ```
+ *
+ * @param callback1 - The first callback to be called
+ * @param callback2 - The second callback to be called
+ *
+ * @returns An event callback that calls the callbacks in order, and is stable between renders
+ */
+export declare function useMergedEventCallbacks<Args extends unknown[]>(callback1: ((...args: Args) => void) | undefined, callback2: ((...args: Args) => void) | undefined): (...args: Args) => void;
+
 /**
  * React hook to merge multiple React refs (either MutableRefObjects or ref callbacks) into a single ref callback that
  * updates all provided refs
@@ -667,4 +755,21 @@ export declare const useUnmount: (callback: () => void) => void;
  */
 export declare const videoProperties: Record<string, number>;
 
+/**
+ * Helper type for {@link Slot}. Takes the props we want to support for a slot and adds the ability for `children`
+ * to be a render function that takes those props.
+ */
+declare type WithSlotRenderFunction<Props extends {
+    children?: unknown;
+}> = Props & {
+    children?: Props['children'] | SlotRenderFunction<Props>;
+};
+
+/**
+ * Helper type for {@link Slot}. Adds shorthand types that are assignable to the slot's `children`.
+ */
+declare type WithSlotShorthandValue<Props extends {
+    children?: unknown;
+}> = Props | Extract<SlotShorthandValue, Props['children']>;
+
 export { }

package/lib/compose/getSlots.d.ts

@@ -1,10 +1,10 @@
 import * as React from 'react';
-import { AsIntrinsicElement, ComponentState, ObjectShorthandPropsRecord, ObjectShorthandProps, UnionToIntersection } from './types';
-export declare type Slots<S extends ObjectShorthandPropsRecord> = {
-    [K in keyof S]-?: NonNullable<S[K]> extends AsIntrinsicElement<infer As> ? As : S[K] extends ObjectShorthandProps<infer P> ? React.ElementType<NonNullable<P>> : React.ElementType<NonNullable<S[K]>>;
+import type { AsIntrinsicElement, ComponentState, ExtractSlotProps, SlotPropsRecord, UnionToIntersection } from './types';
+export declare type Slots<S extends SlotPropsRecord> = {
+    [K in keyof S]: ExtractSlotProps<S[K]> extends AsIntrinsicElement<infer As> ? As : ExtractSlotProps<S[K]> extends React.ComponentType<infer P> ? React.ElementType<NonNullable<P>> : React.ElementType<ExtractSlotProps<S[K]>>;
 };
-declare type SlotProps<S extends ObjectShorthandPropsRecord> = {
-    [K in keyof S]-?: NonNullable<S[K]> extends AsIntrinsicElement<infer As> ? UnionToIntersection<JSX.IntrinsicElements[As]> : NonNullable<S[K]> extends ObjectShorthandProps<infer P> ? P : never;
+declare type ObjectSlotProps<S extends SlotPropsRecord> = {
+    [K in keyof S]-?: ExtractSlotProps<S[K]> extends AsIntrinsicElement<infer As> ? UnionToIntersection<JSX.IntrinsicElements[As]> : ExtractSlotProps<S[K]> extends React.ComponentType<infer P> ? P : never;
 };
 /**
  * Given the state and an array of slot names, will break out `slots` and `slotProps`
@@ -15,15 +15,16 @@ declare type SlotProps<S extends ObjectShorthandPropsRecord> = {
  * Slots will render as null if they are rendered as primitives with undefined children.
  *
  * The slotProps will always omit the `as` prop within them, and for slots that are string
- * primitives, the props will be filtered according the the slot type. For example, if the
- * slot is rendered `as: 'a'`, the props will be filtered for acceptable anchor props.
+ * primitives, the props will be filtered according to the slot type by the type system.
+ * For example, if the slot is rendered `as: 'a'`, the props will be filtered for acceptable
+ * anchor props. Note that this is only enforced at build time by Typescript -- there is no
+ * runtime code filtering props in this function.
  *
  * @param state - State including slot definitions
- * @param slotNames - Name of which props are slots
  * @returns An object containing the `slots` map and `slotProps` map.
  */
-export declare function getSlots<R extends ObjectShorthandPropsRecord>(state: ComponentState<R>, slotNames?: (keyof R)[]): {
+export declare function getSlots<R extends SlotPropsRecord>(state: ComponentState<R>): {
     slots: Slots<R>;
-    slotProps: SlotProps<R>;
+    slotProps: ObjectSlotProps<R>;
 };
 export {};

package/lib/compose/getSlots.js

@@ -1,5 +1,4 @@
 import * as React from 'react';
-import { nullRender } from './nullRender';
 import { omit } from '../utils/omit';
 /**
  * Given the state and an array of slot names, will break out `slots` and `slotProps`
@@ -10,17 +9,19 @@ import { omit } from '../utils/omit';
  * Slots will render as null if they are rendered as primitives with undefined children.
  *
  * The slotProps will always omit the `as` prop within them, and for slots that are string
- * primitives, the props will be filtered according the the slot type. For example, if the
- * slot is rendered `as: 'a'`, the props will be filtered for acceptable anchor props.
+ * primitives, the props will be filtered according to the slot type by the type system.
+ * For example, if the slot is rendered `as: 'a'`, the props will be filtered for acceptable
+ * anchor props. Note that this is only enforced at build time by Typescript -- there is no
+ * runtime code filtering props in this function.
  *
  * @param state - State including slot definitions
- * @param slotNames - Name of which props are slots
  * @returns An object containing the `slots` map and `slotProps` map.
  */
 
-export function getSlots(state, slotNames = ['root']) {
+export function getSlots(state) {
   const slots = {};
   const slotProps = {};
+  const slotNames = Object.keys(state.components);
 
   for (const slotName of slotNames) {
     const [slot, props] = getSlot(state, slotName);
@@ -38,7 +39,7 @@ function getSlot(state, slotName) {
   var _a, _b, _c;
 
   if (state[slotName] === undefined) {
-    return [nullRender, undefined];
+    return [null, undefined];
   }
 
   const {

package/lib/compose/getSlots.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/compose/getSlots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAZ,MAAuB,OAAvB;AAUA,SAAS,UAAT,QAA2B,cAA3B;AACA,SAAS,IAAT,QAAqB,eAArB;AAqBA;;;;;;;;;;;;;;;AAeG;;AACH,OAAM,SAAU,QAAV,CACJ,KADI,EAEJ,SAAA,GAAyB,CAAC,MAAD,CAFrB,EAE6B;AAKjC,QAAM,KAAK,GAAG,EAAd;AACA,QAAM,SAAS,GAAG,EAAlB;;AAEA,OAAK,MAAM,QAAX,IAAuB,SAAvB,EAAkC;AAChC,UAAM,CAAC,IAAD,EAAO,KAAP,IAAgB,OAAO,CAAC,KAAD,EAAQ,QAAR,CAA7B;AACA,IAAA,KAAK,CAAC,QAAD,CAAL,GAAkB,IAAlB;AACA,IAAA,SAAS,CAAC,QAAD,CAAT,GAAsB,KAAtB;AACD;;AACD,SAAO;AAAE,IAAA,KAAF;AAAS,IAAA,SAAS,EAAG;AAArB,GAAP;AACD;;AAED,SAAS,OAAT,CACE,KADF,EAEE,QAFF,EAEa;;;AAEX,MAAI,KAAK,CAAC,QAAD,CAAL,KAAoB,SAAxB,EAAmC;AACjC,WAAO,CAAC,UAAD,EAAa,SAAb,CAAP;AACD;;AACD,QAAM;AAAE,IAAA,QAAF;AAAY,IAAA,EAAE,EAAE,MAAhB;AAAwB,OAAG;AAA3B,MAAoC,KAAK,CAAC,QAAD,CAA/C;AAEA,QAAM,IAAI,GAAI,CAAA,CAAA,EAAA,GAAA,KAAK,CAAC,UAAN,MAAgB,IAAhB,IAAgB,EAAA,KAAA,KAAA,CAAhB,GAAgB,KAAA,CAAhB,GAAgB,EAAA,CAAG,QAAH,CAAhB,MAAiC,SAAjC,IAA8C,OAAO,KAAK,CAAC,UAAN,CAAiB,QAAjB,CAAP,KAAsC,QAApF,GACV,MAAM,KAAA,CAAA,EAAA,GAAI,KAAK,CAAC,UAAV,MAAoB,IAApB,IAAoB,EAAA,KAAA,KAAA,CAApB,GAAoB,KAAA,CAApB,GAAoB,EAAA,CAAG,QAAH,CAApB,CAAN,IAA0C,KADhC,GAEV,KAAK,CAAC,UAAN,CAAiB,QAAjB,CAFJ;;AAIA,MAAI,OAAO,QAAP,KAAoB,UAAxB,EAAoC;AAClC,UAAM,MAAM,GAAG,QAAf;AACA,WAAO,CACL,KAAK,CAAC,QADD,EAEJ;AACC,MAAA,QAAQ,EAAE,MAAM,CAAC,IAAD,EAAO,IAAP;AADjB,KAFI,CAAP;AAMD;;AAED,QAAM,gBAAgB,GAAG,OAAO,IAAP,KAAgB,QAAhB,KAAwB,CAAA,EAAA,GAAI,KAAK,CAAC,QAAD,CAAT,MAAmB,IAAnB,IAAmB,EAAA,KAAA,KAAA,CAAnB,GAAmB,KAAA,CAAnB,GAAmB,EAAA,CAAE,EAA7C,CAAzB;AACA,QAAM,SAAS,GAAI,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,QAAD,CAAN,EAAmB,CAAC,IAAD,CAAnB,CAAP,GAAoC,KAAK,CAAC,QAAD,CAA5E;AAEA,SAAO,CAAC,IAAD,EAAO,SAAP,CAAP;AACD","sourceRoot":""}
+{"version":3,"sources":["../../src/compose/getSlots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAZ,MAAuB,OAAvB;AAEA,SAAS,IAAT,QAAqB,eAArB;AA6BA;;;;;;;;;;;;;;;;AAgBG;;AACH,OAAM,SAAU,QAAV,CACJ,KADI,EACoB;AAKxB,QAAM,KAAK,GAAG,EAAd;AACA,QAAM,SAAS,GAAG,EAAlB;AAEA,QAAM,SAAS,GAAgB,MAAM,CAAC,IAAP,CAAY,KAAK,CAAC,UAAlB,CAA/B;;AACA,OAAK,MAAM,QAAX,IAAuB,SAAvB,EAAkC;AAChC,UAAM,CAAC,IAAD,EAAO,KAAP,IAAgB,OAAO,CAAC,KAAD,EAAQ,QAAR,CAA7B;AACA,IAAA,KAAK,CAAC,QAAD,CAAL,GAAkB,IAAlB;AACA,IAAA,SAAS,CAAC,QAAD,CAAT,GAAsB,KAAtB;AACD;;AACD,SAAO;AAAE,IAAA,KAAF;AAAS,IAAA,SAAS,EAAG;AAArB,GAAP;AACD;;AAED,SAAS,OAAT,CACE,KADF,EAEE,QAFF,EAEa;;;AAEX,MAAI,KAAK,CAAC,QAAD,CAAL,KAAoB,SAAxB,EAAmC;AACjC,WAAO,CAAC,IAAD,EAAO,SAAP,CAAP;AACD;;AACD,QAAM;AAAE,IAAA,QAAF;AAAY,IAAA,EAAE,EAAE,MAAhB;AAAwB,OAAG;AAA3B,MAAoC,KAAK,CAAC,QAAD,CAA/C;AAEA,QAAM,IAAI,GAAI,CAAA,CAAA,EAAA,GAAA,KAAK,CAAC,UAAN,MAAgB,IAAhB,IAAgB,EAAA,KAAA,KAAA,CAAhB,GAAgB,KAAA,CAAhB,GAAgB,EAAA,CAAG,QAAH,CAAhB,MAAiC,SAAjC,IAA8C,OAAO,KAAK,CAAC,UAAN,CAAiB,QAAjB,CAAP,KAAsC,QAApF,GACV,MAAM,KAAI,CAAA,EAAA,GAAA,KAAK,CAAC,UAAN,MAAgB,IAAhB,IAAgB,EAAA,KAAA,KAAA,CAAhB,GAAgB,KAAA,CAAhB,GAAgB,EAAA,CAAG,QAAH,CAApB,CAAN,IAA0C,KADhC,GAEV,KAAK,CAAC,UAAN,CAAiB,QAAjB,CAFJ;;AAIA,MAAI,OAAO,QAAP,KAAoB,UAAxB,EAAoC;AAClC,UAAM,MAAM,GAAG,QAAf;AACA,WAAO,CACL,KAAK,CAAC,QADD,EAEJ;AACC,MAAA,QAAQ,EAAE,MAAM,CAAC,IAAD,EAAO,IAAP;AADjB,KAFI,CAAP;AAMD;;AAED,QAAM,gBAAgB,GAAG,OAAO,IAAP,KAAgB,QAAhB,KAA4B,CAAA,EAAA,GAAA,KAAK,CAAC,QAAD,CAAL,MAAe,IAAf,IAAe,EAAA,KAAA,KAAA,CAAf,GAAe,KAAA,CAAf,GAAe,EAAA,CAAE,EAA7C,CAAzB;AACA,QAAM,SAAS,GAAI,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,QAAD,CAAN,EAAmB,CAAC,IAAD,CAAnB,CAAP,GAAoC,KAAK,CAAC,QAAD,CAA5E;AAEA,SAAO,CAAC,IAAD,EAAO,SAAP,CAAP;AACD","sourceRoot":""}

package/lib/compose/index.d.ts

@@ -1,4 +1,3 @@
 export * from './getSlots';
-export * from './nullRender';
 export * from './resolveShorthand';
 export * from './types';

package/lib/compose/index.js

@@ -1,5 +1,4 @@
 export * from './getSlots';
-export * from './nullRender';
 export * from './resolveShorthand';
 export * from './types';
 //# sourceMappingURL=index.js.map

package/lib/compose/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compose/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compose/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC"}

package/lib/compose/resolveShorthand.d.ts

@@ -1,12 +1,16 @@
-import type { DefaultObjectShorthandProps, ShorthandProps } from './types';
-export declare type ResolveShorthandOptions<Props extends Record<string, any>, Required extends boolean = false> = {
+import type { ReplaceNullWithUndefined, SlotShorthandValue, UnknownSlotProps } from './types';
+export declare type ResolveShorthandOptions<Props, Required extends boolean = false> = {
     required?: Required;
     defaultProps?: Props;
 };
+export declare type ResolveShorthandFunction<Props extends UnknownSlotProps = UnknownSlotProps> = {
+    <P extends Props | null>(value: P | SlotShorthandValue | undefined, options?: ResolveShorthandOptions<P, true>): ReplaceNullWithUndefined<P>;
+    <P extends Props | null>(value: P | SlotShorthandValue | undefined, options?: ResolveShorthandOptions<P, boolean>): ReplaceNullWithUndefined<P> | undefined;
+};
 /**
- * Resolves ShorthandProps into ObjectShorthandProps, to ensure normalization of the signature
+ * Resolves shorthands into slot props, to ensure normalization of the signature
  * being passed down to getSlots method
- * @param value - the base ShorthandProps
- * @param options - options to resolve ShorthandProps
+ * @param value - the base shorthand props
+ * @param options - options to resolve shorthand props
  */
-export declare function resolveShorthand<Props extends DefaultObjectShorthandProps, Required extends boolean = false>(value: ShorthandProps<Props>, options?: ResolveShorthandOptions<Props, Required>): Required extends false ? Props | undefined : Props;
+export declare const resolveShorthand: ResolveShorthandFunction;

package/lib/compose/resolveShorthand.js

@@ -1,12 +1,12 @@
 import { isValidElement } from 'react';
 /**
- * Resolves ShorthandProps into ObjectShorthandProps, to ensure normalization of the signature
+ * Resolves shorthands into slot props, to ensure normalization of the signature
  * being passed down to getSlots method
- * @param value - the base ShorthandProps
- * @param options - options to resolve ShorthandProps
+ * @param value - the base shorthand props
+ * @param options - options to resolve shorthand props
  */
 
-export function resolveShorthand(value, options) {
+export const resolveShorthand = (value, options) => {
   const {
     required = false,
     defaultProps
@@ -27,5 +27,5 @@ export function resolveShorthand(value, options) {
   return defaultProps ? { ...defaultProps,
     ...resolvedShorthand
   } : resolvedShorthand;
-}
+};
 //# sourceMappingURL=resolveShorthand.js.map