@pyreon/elements 0.11.1 → 0.11.3

package/src/__tests__/utils.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest"
+import { getShouldBeEmpty, isInlineElement } from "../Element/utils"
+import { isWebFixNeeded } from "../helpers/Wrapper/utils"
+
+describe("isInlineElement", () => {
+  it("returns true for inline elements", () => {
+    expect(isInlineElement("span")).toBe(true)
+    expect(isInlineElement("a")).toBe(true)
+    expect(isInlineElement("button")).toBe(true)
+    expect(isInlineElement("input")).toBe(true)
+    expect(isInlineElement("label")).toBe(true)
+    expect(isInlineElement("strong")).toBe(true)
+    expect(isInlineElement("em")).toBe(true)
+    expect(isInlineElement("img")).toBe(true)
+  })
+
+  it("returns false for block elements", () => {
+    expect(isInlineElement("div")).toBe(false)
+    expect(isInlineElement("p")).toBe(false)
+    expect(isInlineElement("section")).toBe(false)
+    expect(isInlineElement("header")).toBe(false)
+  })
+
+  it("returns false for undefined", () => {
+    expect(isInlineElement(undefined)).toBe(false)
+  })
+
+  it("returns false for empty string", () => {
+    expect(isInlineElement("")).toBe(false)
+  })
+})
+
+describe("getShouldBeEmpty", () => {
+  it("returns true for void elements", () => {
+    expect(getShouldBeEmpty("br")).toBe(true)
+    expect(getShouldBeEmpty("img")).toBe(true)
+    expect(getShouldBeEmpty("input")).toBe(true)
+    expect(getShouldBeEmpty("hr")).toBe(true)
+    expect(getShouldBeEmpty("embed")).toBe(true)
+  })
+
+  it("returns false for non-void elements", () => {
+    expect(getShouldBeEmpty("div")).toBe(false)
+    expect(getShouldBeEmpty("span")).toBe(false)
+    expect(getShouldBeEmpty("p")).toBe(false)
+  })
+
+  it("returns false for undefined", () => {
+    expect(getShouldBeEmpty(undefined)).toBe(false)
+  })
+})
+
+describe("isWebFixNeeded", () => {
+  it("returns true for button, fieldset, legend", () => {
+    expect(isWebFixNeeded("button")).toBe(true)
+    expect(isWebFixNeeded("fieldset")).toBe(true)
+    expect(isWebFixNeeded("legend")).toBe(true)
+  })
+
+  it("returns false for other elements", () => {
+    expect(isWebFixNeeded("div")).toBe(false)
+    expect(isWebFixNeeded("span")).toBe(false)
+    expect(isWebFixNeeded("input")).toBe(false)
+  })
+
+  it("returns false for undefined", () => {
+    expect(isWebFixNeeded(undefined)).toBe(false)
+  })
+})

package/src/constants.ts

@@ -0,0 +1 @@
+export const PKG_NAME = "@pyreon/elements" as const

package/src/helpers/Content/component.tsx

@@ -0,0 +1,51 @@
+/**
+ * Content area used inside Element to render one of the three
+ * layout slots (before, content, after). Passes alignment, direction,
+ * gap, and equalCols styling props to the underlying styled component.
+ * Adds a `data-pyr-element` attribute in development for debugging.
+ *
+ * Children are rendered via core `render()`.
+ */
+import { render } from "@pyreon/ui-core"
+import { IS_DEVELOPMENT } from "../../utils"
+import Styled from "./styled"
+import type { Props } from "./types"
+
+const Component = ({
+  contentType,
+  tag,
+  parentDirection,
+  direction,
+  alignX,
+  alignY,
+  equalCols,
+  gap,
+  extendCss,
+  children,
+  ...props
+}: Partial<Props>) => {
+  const debugProps = IS_DEVELOPMENT
+    ? {
+        "data-pyr-element": contentType,
+      }
+    : {}
+
+  const stylingProps = {
+    contentType,
+    parentDirection,
+    direction,
+    alignX,
+    alignY,
+    equalCols,
+    gap,
+    extraStyles: extendCss,
+  }
+
+  return (
+    <Styled as={tag} $contentType={contentType} $element={stylingProps} {...debugProps} {...props}>
+      {render(children)}
+    </Styled>
+  )
+}
+
+export default Component

package/src/helpers/Content/index.ts

@@ -0,0 +1,3 @@
+import component from "./component"
+
+export default component

package/src/helpers/Content/styled.ts

@@ -0,0 +1,105 @@
+/**
+ * Styled component for content areas (before/content/after). Applies
+ * responsive flex alignment, gap spacing between slots based on parent
+ * direction (margin-right for inline, margin-bottom for rows), and
+ * equalCols flex distribution. The "content" slot gets `flex: 1` to
+ * fill remaining space between before and after.
+ */
+import { config } from "@pyreon/ui-core"
+import { alignContent, extendCss, makeItResponsive, value } from "@pyreon/unistyle"
+import type { ResponsiveStylesCallback } from "../../types"
+import type { StyledProps, ThemeProps } from "./types"
+
+const { styled, css, component } = config
+
+const equalColsCSS = `
+  flex: 1;
+`
+
+const typeContentCSS = `
+  flex: 1;
+`
+
+// --------------------------------------------------------
+// calculate spacing between before / content / after
+// --------------------------------------------------------
+const gapDimensions = {
+  inline: {
+    before: "margin-right",
+    after: "margin-left",
+  },
+  reverseInline: {
+    before: "margin-right",
+    after: "margin-left",
+  },
+  rows: {
+    before: "margin-bottom",
+    after: "margin-top",
+  },
+  reverseRows: {
+    before: "margin-bottom",
+    after: "margin-top",
+  },
+} as const
+
+const calculateGap = ({
+  direction,
+  type,
+  value: gapValue,
+}: {
+  direction: keyof typeof gapDimensions
+  type: ThemeProps["contentType"]
+  value: string | number | null | undefined
+}) => {
+  if (!direction || !type || type === "content") return undefined
+
+  const finalStyles = `${gapDimensions[direction][type]}: ${gapValue};`
+
+  return finalStyles
+}
+
+// --------------------------------------------------------
+// calculations of styles to be rendered
+// --------------------------------------------------------
+const styles: ResponsiveStylesCallback = ({ css: cssFn, theme: t, rootSize }) => cssFn`
+  ${alignContent({
+    direction: t.direction,
+    alignX: t.alignX,
+    alignY: t.alignY,
+  })};
+
+  ${t.equalCols && equalColsCSS};
+
+  ${
+    t.gap &&
+    t.contentType &&
+    calculateGap({
+      direction: t.parentDirection,
+      type: t.contentType,
+      value: value(t.gap, rootSize),
+    })
+  };
+
+  ${t.extraStyles && extendCss(t.extraStyles as Parameters<typeof extendCss>[0])};
+`
+
+const platformCSS = `box-sizing: border-box;`
+
+const StyledComponent = styled(component)`
+  ${platformCSS};
+
+  display: flex;
+  align-self: stretch;
+  flex-wrap: wrap;
+
+  ${(({ $contentType }: StyledProps) => $contentType === "content" && typeContentCSS) as any};
+
+  ${makeItResponsive({
+    key: "$element",
+    styles,
+    css,
+    normalize: true,
+  })};
+`
+
+export default StyledComponent

package/src/helpers/Content/types.ts

@@ -0,0 +1,49 @@
+import type { HTMLTags } from "@pyreon/ui-core"
+import type {
+  AlignX,
+  AlignY,
+  Content,
+  ContentAlignX,
+  ContentAlignY,
+  ContentBoolean,
+  ContentDirection,
+  ContentSimpleValue,
+  Css,
+  Direction,
+  ExtendCss,
+  Responsive,
+  ResponsiveBoolType,
+} from "../../types"
+
+export interface Props {
+  parentDirection: Direction | undefined
+  gap: Responsive | undefined
+  contentType: "before" | "content" | "after" | undefined
+  children: Content
+  tag: HTMLTags | undefined
+  direction: Direction | undefined
+  alignX: AlignX | undefined
+  alignY: AlignY | undefined
+  equalCols: ResponsiveBoolType | undefined
+  extendCss: ExtendCss | undefined
+}
+
+export interface StyledProps {
+  $element: Pick<
+    Props,
+    "contentType" | "parentDirection" | "direction" | "alignX" | "alignY" | "equalCols" | "gap"
+  > & {
+    extraStyles: Props["extendCss"]
+  }
+  $contentType: Props["contentType"]
+}
+
+export type ThemeProps = Pick<Props, "contentType"> & {
+  parentDirection: ContentDirection
+  direction: ContentDirection
+  alignX: ContentAlignX
+  alignY: ContentAlignY
+  equalCols?: ContentBoolean
+  gap?: ContentSimpleValue
+  extraStyles?: Css
+}

package/src/helpers/Iterator/component.tsx

@@ -0,0 +1,252 @@
+/**
+ * Data-driven list renderer that supports three input modes: children,
+ * an array of primitives, or an array of objects.
+ * Each item receives positional metadata (first, last, odd, even, position)
+ * and optional injected props via `itemProps`. Items can be individually
+ * wrapped with `wrapComponent`. Children always take priority over the
+ * component+data prop pattern.
+ */
+
+import type { VNode, VNodeChild } from "@pyreon/core"
+import { Fragment } from "@pyreon/core"
+import { isEmpty, render } from "@pyreon/ui-core"
+import type { ExtendedProps, ObjectValue, Props, SimpleValue } from "./types"
+
+type ClassifiedData =
+  | { type: "simple"; data: SimpleValue[] }
+  | { type: "complex"; data: ObjectValue[] }
+  | null
+
+const classifyData = (data: unknown[]): ClassifiedData => {
+  const items = data.filter(
+    (item) =>
+      item != null && !(typeof item === "object" && isEmpty(item as Record<string, unknown>)),
+  )
+
+  if (items.length === 0) return null
+
+  let isSimple = true
+  let isComplex = true
+
+  for (const item of items) {
+    if (typeof item === "string" || typeof item === "number") {
+      isComplex = false
+    } else if (typeof item === "object") {
+      isSimple = false
+    } else {
+      isSimple = false
+      isComplex = false
+    }
+  }
+
+  if (isSimple) return { type: "simple", data: items as SimpleValue[] }
+  if (isComplex) return { type: "complex", data: items as ObjectValue[] }
+  return null
+}
+
+const RESERVED_PROPS = [
+  "children",
+  "component",
+  "wrapComponent",
+  "data",
+  "itemKey",
+  "valueName",
+  "itemProps",
+  "wrapProps",
+] as const
+
+type AttachItemProps = ({ i, length }: { i: number; length: number }) => ExtendedProps
+
+const attachItemProps: AttachItemProps = ({ i, length }: { i: number; length: number }) => {
+  const position = i + 1
+
+  return {
+    index: i,
+    first: position === 1,
+    last: position === length,
+    odd: position % 2 === 1,
+    even: position % 2 === 0,
+    position,
+  }
+}
+
+const Component = (props: Props) => {
+  const {
+    itemKey,
+    valueName,
+    children,
+    component,
+    data,
+    wrapComponent: Wrapper,
+    wrapProps,
+    itemProps,
+  } = props
+
+  const injectItemProps = typeof itemProps === "function" ? itemProps : () => itemProps
+
+  const injectWrapItemProps = typeof wrapProps === "function" ? wrapProps : () => wrapProps
+
+  const getKey = (item: string | number, index: number) => {
+    if (typeof itemKey === "function") return itemKey(item, index)
+    return index
+  }
+
+  const renderChild = (child: VNodeChild, total = 1, i = 0) => {
+    if (!itemProps && !Wrapper) return child
+
+    const extendedProps = attachItemProps({
+      i,
+      length: total,
+    })
+
+    const finalItemProps = itemProps ? injectItemProps({}, extendedProps) : {}
+
+    if (Wrapper) {
+      const finalWrapProps = wrapProps ? injectWrapItemProps({}, extendedProps) : {}
+
+      return (
+        <Wrapper key={i} {...finalWrapProps}>
+          {render(child, finalItemProps)}
+        </Wrapper>
+      )
+    }
+
+    return render(child, {
+      key: i,
+      ...finalItemProps,
+    })
+  }
+
+  // --------------------------------------------------------
+  // render children
+  // --------------------------------------------------------
+  const renderChildren = () => {
+    if (!children) return null
+
+    // if children is Array
+    if (Array.isArray(children)) {
+      return children.map((item, i) => renderChild(item, children.length, i))
+    }
+
+    // if children is Fragment — check VNode type
+    if (
+      typeof children === "object" &&
+      "type" in (children as VNode) &&
+      (children as VNode).type === Fragment
+    ) {
+      const fragmentChildren = (children as VNode).children as VNodeChild[]
+      const childrenLength = fragmentChildren.length
+
+      return fragmentChildren.map((item, i) => renderChild(item, childrenLength, i))
+    }
+
+    // if single child
+    return renderChild(children)
+  }
+
+  // --------------------------------------------------------
+  // render array of strings or numbers
+  // --------------------------------------------------------
+  const renderSimpleArray = (simpleData: SimpleValue[]) => {
+    const { length } = simpleData
+
+    if (length === 0) return null
+
+    return simpleData.map((item, i) => {
+      const key = getKey(item, i)
+      const keyName = valueName ?? "children"
+      const extendedProps = attachItemProps({
+        i,
+        length,
+      })
+
+      const finalItemProps = {
+        ...(itemProps ? injectItemProps({ [keyName]: item }, extendedProps) : {}),
+        [keyName]: item,
+      }
+
+      if (Wrapper) {
+        const finalWrapProps = wrapProps
+          ? injectWrapItemProps({ [keyName]: item }, extendedProps)
+          : {}
+
+        return (
+          <Wrapper key={key} {...finalWrapProps}>
+            {render(component, finalItemProps)}
+          </Wrapper>
+        )
+      }
+
+      return render(component, { key, ...finalItemProps })
+    })
+  }
+
+  // --------------------------------------------------------
+  // render array of objects
+  // --------------------------------------------------------
+  const getObjectKey = (item: ObjectValue, index: number) => {
+    if (!itemKey) return item.key ?? item.id ?? item.itemId ?? index
+    if (typeof itemKey === "function") return itemKey(item, index)
+    if (typeof itemKey === "string") return item[itemKey]
+
+    return index
+  }
+
+  const renderComplexArray = (complexData: ObjectValue[]) => {
+    const { length } = complexData
+
+    if (length === 0) return null
+
+    return complexData.map((item, i) => {
+      const { component: itemComponent, ...restItem } = item
+      const renderItem = itemComponent ?? component
+      const key = getObjectKey(restItem, i)
+      const extendedProps = attachItemProps({
+        i,
+        length,
+      })
+
+      const finalItemProps = {
+        ...(itemProps ? injectItemProps(item, extendedProps) : {}),
+        ...restItem,
+      }
+
+      if (Wrapper && !itemComponent) {
+        const finalWrapProps = wrapProps ? injectWrapItemProps(item, extendedProps) : {}
+
+        return (
+          <Wrapper key={key} {...finalWrapProps}>
+            {render(renderItem, finalItemProps)}
+          </Wrapper>
+        )
+      }
+
+      return render(renderItem, { key, ...finalItemProps })
+    })
+  }
+
+  // --------------------------------------------------------
+  // render list items
+  // --------------------------------------------------------
+  const renderItems = (): VNodeChild => {
+    // children have priority over props component + data
+    if (children) return renderChildren() as VNodeChild
+
+    // render props component + data
+    if (component && Array.isArray(data)) {
+      const classified = classifyData(data)
+      if (!classified) return null
+      if (classified.type === "simple") return renderSimpleArray(classified.data) as VNodeChild
+      return renderComplexArray(classified.data) as VNodeChild
+    }
+
+    return null
+  }
+
+  return renderItems()
+}
+
+export default Object.assign(Component, {
+  isIterator: true as const,
+  RESERVED_PROPS,
+})

package/src/helpers/Iterator/index.ts

@@ -0,0 +1,13 @@
+import component from "./component"
+import type {
+  ElementType,
+  ExtendedProps,
+  ObjectValue,
+  Props,
+  PropsCallback,
+  SimpleValue,
+} from "./types"
+
+export type { ElementType, ExtendedProps, ObjectValue, Props, PropsCallback, SimpleValue }
+
+export default component

package/src/helpers/Iterator/types.ts

@@ -0,0 +1,79 @@
+import type { ComponentFn, VNodeChild } from "@pyreon/core"
+import type { HTMLTags } from "@pyreon/ui-core"
+
+export type MaybeNull = undefined | null
+export type TObj = Record<string, unknown>
+export type SimpleValue = string | number
+export type ObjectValue = Partial<{
+  id: SimpleValue
+  key: SimpleValue
+  itemId: SimpleValue
+  component: ElementType
+}> &
+  Record<string, unknown>
+
+export type ElementType<T extends Record<string, unknown> = any> = ComponentFn<T> | HTMLTags
+
+export type ExtendedProps = {
+  index: number
+  first: boolean
+  last: boolean
+  odd: boolean
+  even: boolean
+  position: number
+}
+
+export type PropsCallback =
+  | TObj
+  | ((
+      itemProps: Record<string, never> | Record<string, SimpleValue> | ObjectValue,
+      extendedProps: ExtendedProps,
+    ) => TObj)
+
+export type Props = Partial<{
+  /**
+   * Valid children
+   */
+  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)
+}>

package/src/helpers/Wrapper/component.tsx

@@ -0,0 +1,78 @@
+/**
+ * Wrapper component that serves as the outermost styled container for Element.
+ * On web, it detects button/fieldset/legend tags and applies a two-layer flex
+ * fix (parent + child Styled) because these HTML elements do not natively
+ * support `display: flex` consistently across browsers.
+ */
+import { IS_DEVELOPMENT } from "../../utils"
+import Styled from "./styled"
+import type { Props } from "./types"
+import { isWebFixNeeded } from "./utils"
+
+const DEV_PROPS: Record<string, string> = IS_DEVELOPMENT ? { "data-pyr-element": "Element" } : {}
+
+const Component = ({
+  children,
+  tag,
+  block,
+  extendCss,
+  direction,
+  alignX,
+  alignY,
+  equalCols,
+  isInline,
+  ref,
+  ...props
+}: Partial<Props> & { ref?: any }) => {
+  const COMMON_PROPS = {
+    ...props,
+    ...DEV_PROPS,
+    ref,
+    as: tag,
+  }
+
+  const needsFix = !props.dangerouslySetInnerHTML && isWebFixNeeded(tag)
+
+  const normalElement = {
+    block,
+    direction,
+    alignX,
+    alignY,
+    equalCols,
+    extraStyles: extendCss,
+  }
+
+  const parentFixElement = {
+    parentFix: true as const,
+    block,
+    extraStyles: extendCss,
+  }
+
+  const childFixElement = {
+    childFix: true as const,
+    direction,
+    alignX,
+    alignY,
+    equalCols,
+  }
+
+  if (!needsFix) {
+    return (
+      <Styled {...COMMON_PROPS} $element={normalElement}>
+        {children}
+      </Styled>
+    )
+  }
+
+  const asTag = isInline ? "span" : "div"
+
+  return (
+    <Styled {...COMMON_PROPS} $element={parentFixElement}>
+      <Styled as={asTag} $childFix $element={childFixElement}>
+        {children}
+      </Styled>
+    </Styled>
+  )
+}
+
+export default Component