@pyreon/elements 0.14.0 → 0.16.0

package/lib/index.d.ts

@@ -1,8 +1,8 @@
 import { Provider } from "@pyreon/unistyle";
-import * as _pyreon_core0 from "@pyreon/core";
+import * as _$_pyreon_core0 from "@pyreon/core";
 import { ComponentFn, PyreonHTMLAttributes, VNodeChild } from "@pyreon/core";
 import { BreakpointKeys, HTMLTags, HTMLTextTags, config, render } from "@pyreon/ui-core";
-import * as _pyreon_reactivity0 from "@pyreon/reactivity";
+import * as _$_pyreon_reactivity0 from "@pyreon/reactivity";
 
 //#region src/types.d.ts
 type ExtractNullableKeys<T> = { [P in keyof T as T[P] extends null | undefined ? never : P]: T[P] };
@@ -182,54 +182,87 @@ type ExtendedProps = {
   even: boolean;
   position: number;
 };
-type PropsCallback = TObj | ((itemProps: Record<string, never> | Record<string, SimpleValue> | ObjectValue, extendedProps: ExtendedProps) => TObj);
-type Props$1 = Partial<{
+/**
+ * Iterator over an array of strings/numbers. Each item is wrapped in
+ * `{ [valueName]: item }` and that object is what callbacks see + what's
+ * spread onto the rendered component.
+ */
+type SimpleProps<T extends SimpleValue> = {
+  data: Array<T | MaybeNull>; /** A component to be rendered per item. */
+  component: ElementType;
   /**
-   * Valid children
-   */
+   * Key under which each primitive value is exposed to `component` and
+   * callbacks. Defaults to `'children'` at runtime — i.e. the value is
+   * passed to the component as its children.
+   */
+  valueName?: string; /** Optional wrapper around each item. */
+  wrapComponent?: ElementType; /** Stable key per item (defaults to index). */
+  itemKey?: (item: T, index: number) => SimpleValue; /** Extra props merged onto the rendered component, optionally per-item. */
+  itemProps?: TObj | ((item: {
+    [k: string]: T;
+  }, ext: ExtendedProps) => TObj); /** Extra props merged onto the wrapper, optionally per-item. */
+  wrapProps?: TObj | ((item: {
+    [k: string]: T;
+  }, ext: ExtendedProps) => TObj);
+  children?: never;
+};
+/**
+ * Iterator over an array of objects. Each item is spread onto the rendered
+ * component as props. Per-item `component` overrides also work — when an
+ * item carries its own `component` field, the wrapper is bypassed.
+ */
+type ObjectProps<T extends ObjectValue> = {
+  data: Array<T | MaybeNull>; /** Default component to be rendered per item (item-level `component` overrides). */
+  component: ElementType; /** `valueName` is meaningless when iterating objects — TS forbids it. */
+  valueName?: never; /** Optional wrapper around each item. */
+  wrapComponent?: ElementType; /** Stable key per item — pick a key from the item, or compute it. */
+  itemKey?: keyof T | ((item: T, index: number) => SimpleValue); /** Extra props merged onto the rendered component, optionally per-item. */
+  itemProps?: TObj | ((item: T, ext: ExtendedProps) => TObj); /** Extra props merged onto the wrapper, optionally per-item. */
+  wrapProps?: TObj | ((item: T, ext: ExtendedProps) => TObj);
+  children?: never;
+};
+/**
+ * Iterator over `children` — no `data`/`component`. Each child gets
+ * positional metadata via `itemProps` and an optional `wrapComponent`.
+ */
+type ChildrenProps = {
+  children: VNodeChild;
+  data?: never;
+  component?: never;
+  valueName?: never;
+  itemKey?: never;
+  wrapComponent?: ElementType;
+  itemProps?: TObj | ((_: Record<string, never>, ext: ExtendedProps) => TObj);
+  wrapProps?: TObj | ((_: Record<string, never>, ext: ExtendedProps) => TObj);
+};
+type PropsCallback = TObj | ((itemProps: Record<string, never> | Record<string, SimpleValue> | ObjectValue, extendedProps: ExtendedProps) => TObj);
+type LooseProps = Partial<{
   children: VNodeChild;
-  /**
-   * Array of data passed to `component` prop
-   */
   data: Array<SimpleValue | ObjectValue | MaybeNull>;
-  /**
-   * A component to be rendered within list
-   */
   component: ElementType;
-  /**
-   * Defines name of the prop to be passed to the iteration component
-   * when **data** prop is type of `string[]`, `number[]` or combination
-   * of both. Otherwise ignored.
-   */
   valueName: string;
-  /**
-   * A component to be rendered within list. `wrapComponent`
-   * wraps `component`. Therefore it can be used to enhance the behavior
-   * of the list component
-   */
   wrapComponent: ElementType;
-  /**
-   * Extension of **item** `component` props to be passed
-   */
   itemProps: PropsCallback;
-  /**
-   * Extension of **item** `wrapComponent` props to be passed
-   */
-  wrapProps?: PropsCallback;
-  /**
-   * Extension of **item** `wrapComponent` props to be passed
-   */
-  itemKey?: keyof ObjectValue | ((item: SimpleValue | Omit<ObjectValue, 'component'>, index: number) => SimpleValue);
+  wrapProps: PropsCallback;
+  itemKey: keyof ObjectValue | ((item: SimpleValue | Omit<ObjectValue, 'component'>, index: number) => SimpleValue);
 }>;
+type Props$1<T = unknown> = unknown extends T ? LooseProps : T extends SimpleValue ? SimpleProps<T> : T extends ObjectValue ? ObjectProps<T> : ChildrenProps;
 //#endregion
 //#region src/helpers/Iterator/component.d.ts
-declare const _default: ((props: Props$1) => VNodeChild) & {
+declare const RESERVED_PROPS: readonly ["children", "component", "wrapComponent", "data", "itemKey", "valueName", "itemProps", "wrapProps"];
+interface IteratorComponent {
+  <T extends SimpleValue>(props: SimpleProps<T>): VNodeChild;
+  <T extends ObjectValue>(props: ObjectProps<T>): VNodeChild;
+  (props: ChildrenProps): VNodeChild;
+  (props: LooseProps): VNodeChild;
   isIterator: true;
-  RESERVED_PROPS: readonly ["children", "component", "wrapComponent", "data", "itemKey", "valueName", "itemProps", "wrapProps"];
-};
+  RESERVED_PROPS: typeof RESERVED_PROPS;
+  displayName?: string;
+}
+declare const Iterator: IteratorComponent;
 //#endregion
 //#region src/List/component.d.ts
-type ListProps = {
+type ListOnly = {
   /**
    * A boolean value. When set to `false`, component returns fragment.
    * When set to `true`, component returns as the **root** element `Element`
@@ -239,14 +272,38 @@ type ListProps = {
   /**
    * Label prop from `Element` component is being ignored.
    */
-  label: never;
+  label?: never;
   /**
    * Content prop from `Element` component is being ignored.
    */
-  content: never;
+  content?: never;
 };
-type Props$2 = MergeTypes<[Props$1, ListProps]> & Partial<Omit<Props, 'children' | 'content' | 'label'>>;
-declare const Component$1: PyreonElement<Props$2>;
+/**
+ * Props that List accepts on top of the Iterator branch — the Element prop
+ * surface (so `tag`, `direction`, `alignX`, etc. forward when
+ * `rootElement` is true) plus the List-only toggle.
+ */
+type ListExtras = Partial<Omit<Props, 'children' | 'content' | 'label'>> & ListOnly;
+/**
+ * Public Props — generic over the data element type so callers get the same
+ * inference Iterator does, plus the List-specific `rootElement` toggle and
+ * Element prop forwarding.
+ *
+ *   Props<string>          → SimpleProps & ListExtras  (valueName REQUIRED)
+ *   Props<{ id; name }>    → ObjectProps & ListExtras  (valueName FORBIDDEN)
+ *   Props<unknown> / Props → LooseProps & ListExtras   (today's behavior)
+ */
+type Props$2<T = unknown> = MergeTypes<[Props$1<T>, ListExtras]>;
+interface ListComponent {
+  <T extends SimpleValue>(props: SimpleProps<T> & ListExtras): VNodeChild;
+  <T extends ObjectValue>(props: ObjectProps<T> & ListExtras): VNodeChild;
+  (props: ChildrenProps & ListExtras): VNodeChild;
+  (props: LooseProps & ListExtras): VNodeChild;
+  displayName?: string;
+  pkgName?: string;
+  PYREON__COMPONENT?: string;
+}
+declare const _default: ListComponent;
 //#endregion
 //#region src/Overlay/context.d.ts
 interface OverlayContext {
@@ -254,9 +311,9 @@ interface OverlayContext {
   setBlocked: () => void;
   setUnblocked: () => void;
 }
-declare const Component$3: (props: OverlayContext & {
+declare const Component$2: (props: OverlayContext & {
   children: VNodeChild;
-}) => _pyreon_core0.VNode;
+}) => _$_pyreon_core0.VNode;
 //#endregion
 //#region src/Overlay/positioning.d.ts
 type Align$1 = 'bottom' | 'top' | 'left' | 'right';
@@ -304,10 +361,10 @@ declare const useOverlay: ({
 }?: Partial<UseOverlayProps>) => {
   triggerRef: (node: HTMLElement | null) => void;
   contentRef: (node: HTMLElement | null) => void;
-  active: _pyreon_reactivity0.Signal<boolean>;
+  active: _$_pyreon_reactivity0.Signal<boolean>;
   align: Align$1;
-  alignX: _pyreon_reactivity0.Signal<AlignX$2>;
-  alignY: _pyreon_reactivity0.Signal<AlignY$2>;
+  alignX: _$_pyreon_reactivity0.Signal<AlignX$2>;
+  alignY: _$_pyreon_reactivity0.Signal<AlignY$2>;
   showContent: () => void;
   hideContent: () => void;
   blocked: () => boolean;
@@ -315,8 +372,8 @@ declare const useOverlay: ({
   setUnblocked: () => void;
   setupListeners: () => () => void;
   Provider: (props: OverlayContext & {
-    children: _pyreon_core0.VNodeChild;
-  }) => _pyreon_core0.VNode;
+    children: _$_pyreon_core0.VNodeChild;
+  }) => _$_pyreon_core0.VNode;
 };
 //#endregion
 //#region src/Overlay/component.d.ts
@@ -343,24 +400,24 @@ type Props$3 = {
   triggerRefName?: string;
   contentRefName?: string;
 } & UseOverlayProps;
-declare const Component$2: PyreonComponent<Props$3>;
+declare const Component$1: PyreonComponent<Props$3>;
 //#endregion
 //#region src/Portal/component.d.ts
 interface Props$4 {
   /**
-   * Defines a HTML DOM where children to be appended.
+   * DOM element to mount the wrapper into. Defaults to `document.body`.
    */
   DOMLocation?: HTMLElement;
   /**
-   * Children to be rendered within **Portal** component.
+   * Children rendered inside the wrapper.
    */
   children: VNodeChild;
   /**
-   * Valid HTML Tag
+   * HTML tag for the per-instance wrapper element. Defaults to `'div'`.
    */
   tag?: string;
 }
-declare const Component$4: PyreonComponent<Props$4>;
+declare const Component$3: PyreonComponent<Props$4>;
 //#endregion
 //#region src/Text/component.d.ts
 type Props$5 = Partial<{
@@ -385,7 +442,7 @@ type Props$5 = Partial<{
    */
   css: ExtendCss;
 }> & PyreonHTMLAttributes;
-declare const Component$5: PyreonComponent<Props$5> & {
+declare const Component$4: PyreonComponent<Props$5> & {
   isText?: true;
 };
 //#endregion
@@ -404,7 +461,7 @@ interface Props$6 {
    */
   style?: Record<string, unknown> | undefined;
 }
-declare const Component$6: PyreonComponent<Props$6>;
+declare const Component$5: PyreonComponent<Props$6>;
 //#endregion
-export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, _default as Iterator, type Props$1 as IteratorProps, Component$1 as List, type Props$2 as ListProps, type MaybeNull, type ObjectValue, Component$2 as Overlay, type Props$3 as OverlayProps, Component$3 as OverlayProvider, Component$4 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type PyreonElement, type PyreonStatic, type Responsive, type ResponsiveBoolType, type SimpleValue, Component$5 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$6 as Util, type Props$6 as UtilProps, useOverlay };
+export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, Iterator, type ChildrenProps as IteratorChildrenProps, type LooseProps as IteratorLooseProps, type ObjectProps as IteratorObjectProps, type Props$1 as IteratorProps, type SimpleProps as IteratorSimpleProps, _default as List, type Props$2 as ListProps, type MaybeNull, type ObjectValue, Component$1 as Overlay, type Props$3 as OverlayProps, Component$2 as OverlayProvider, Component$3 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type PyreonElement, type PyreonStatic, type Responsive, type ResponsiveBoolType, type SimpleValue, Component$4 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$5 as Util, type Props$6 as UtilProps, useOverlay };
 //# sourceMappingURL=index2.d.ts.map