@pyreon/attrs 0.11.1 → 0.11.3

package/src/__tests__/utils.test.ts

@@ -0,0 +1,241 @@
+import { calculateChainOptions, removeUndefinedProps } from "../utils/attrs"
+import { chainOptions } from "../utils/chaining"
+import { removeNullableValues } from "../utils/collection"
+import { calculateHocsFuncs } from "../utils/compose"
+import { createStaticsEnhancers } from "../utils/statics"
+
+// --------------------------------------------------------
+// removeUndefinedProps
+// --------------------------------------------------------
+describe("removeUndefinedProps", () => {
+  it("should remove properties with undefined values", () => {
+    const result = removeUndefinedProps({
+      a: 1,
+      b: undefined,
+      c: "hello",
+    })
+    expect(result).toEqual({ a: 1, c: "hello" })
+  })
+
+  it("should keep null values", () => {
+    const result = removeUndefinedProps({ a: null, b: undefined })
+    expect(result).toEqual({ a: null })
+  })
+
+  it("should keep false values", () => {
+    const result = removeUndefinedProps({ a: false, b: undefined })
+    expect(result).toEqual({ a: false })
+  })
+
+  it("should keep zero values", () => {
+    const result = removeUndefinedProps({ a: 0, b: undefined })
+    expect(result).toEqual({ a: 0 })
+  })
+
+  it("should keep empty string values", () => {
+    const result = removeUndefinedProps({ a: "", b: undefined })
+    expect(result).toEqual({ a: "" })
+  })
+
+  it("should return empty object when all values are undefined", () => {
+    const result = removeUndefinedProps({ a: undefined, b: undefined })
+    expect(result).toEqual({})
+  })
+
+  it("should return all props when none are undefined", () => {
+    const input = { a: 1, b: "test", c: true }
+    const result = removeUndefinedProps(input)
+    expect(result).toEqual(input)
+  })
+
+  it("should handle empty object", () => {
+    const result = removeUndefinedProps({})
+    expect(result).toEqual({})
+  })
+})
+
+// --------------------------------------------------------
+// removeNullableValues
+// --------------------------------------------------------
+describe("removeNullableValues", () => {
+  it("should remove null values", () => {
+    const result = removeNullableValues({ a: 1, b: null })
+    expect(result).toEqual({ a: 1 })
+  })
+
+  it("should remove undefined values", () => {
+    const result = removeNullableValues({ a: 1, b: undefined })
+    expect(result).toEqual({ a: 1 })
+  })
+
+  it("should remove false values", () => {
+    const result = removeNullableValues({ a: 1, b: false })
+    expect(result).toEqual({ a: 1 })
+  })
+
+  it("should keep zero values", () => {
+    const result = removeNullableValues({ a: 0, b: null })
+    expect(result).toEqual({ a: 0 })
+  })
+
+  it("should keep empty string values", () => {
+    const result = removeNullableValues({ a: "", b: null })
+    expect(result).toEqual({ a: "" })
+  })
+
+  it("should keep truthy values", () => {
+    const result = removeNullableValues({ a: 1, b: "test", c: true })
+    expect(result).toEqual({ a: 1, b: "test", c: true })
+  })
+
+  it("should handle empty object", () => {
+    const result = removeNullableValues({})
+    expect(result).toEqual({})
+  })
+})
+
+// --------------------------------------------------------
+// calculateChainOptions
+// --------------------------------------------------------
+describe("calculateChainOptions", () => {
+  it("should return empty object when no options provided", () => {
+    const calculate = calculateChainOptions(undefined)
+    const result = calculate([{}])
+    expect(result).toEqual({})
+  })
+
+  it("should return empty object for empty options array", () => {
+    const calculate = calculateChainOptions([])
+    const result = calculate([{}])
+    expect(result).toEqual({})
+  })
+
+  it("should execute a single option function", () => {
+    const fn = (props: any) => ({
+      color: props.variant === "primary" ? "blue" : "gray",
+    })
+    const calculate = calculateChainOptions([fn])
+    const result = calculate([{ variant: "primary" }])
+    expect(result).toEqual({ color: "blue" })
+  })
+
+  it("should merge results from multiple option functions", () => {
+    const fn1 = (_: any) => ({ color: "blue" })
+    const fn2 = (_: any) => ({ size: "large" })
+    const calculate = calculateChainOptions([fn1, fn2])
+    const result = calculate([{}])
+    expect(result).toEqual({ color: "blue", size: "large" })
+  })
+
+  it("should let later functions override earlier ones", () => {
+    const fn1 = (_: any) => ({ color: "blue" })
+    const fn2 = (_: any) => ({ color: "red" })
+    const calculate = calculateChainOptions([fn1, fn2])
+    const result = calculate([{}])
+    expect(result).toEqual({ color: "red" })
+  })
+
+  it("should pass arguments to each option function", () => {
+    const fn = vi.fn((_: any) => ({}))
+    const calculate = calculateChainOptions([fn])
+    const props = { variant: "primary" }
+    calculate([props])
+    expect(fn).toHaveBeenCalledWith(props)
+  })
+})
+
+// --------------------------------------------------------
+// chainOptions
+// --------------------------------------------------------
+describe("chainOptions", () => {
+  it("should return default options when opts is undefined", () => {
+    const defaults = [() => ({})]
+    const result = chainOptions(undefined, defaults)
+    expect(result).toEqual(defaults)
+  })
+
+  it("should append function to defaults", () => {
+    const fn1 = () => ({ a: 1 })
+    const fn2 = () => ({ b: 2 })
+    const result = chainOptions(fn2, [fn1])
+    expect(result).toHaveLength(2)
+    expect(result[0]).toBe(fn1)
+    expect(result[1]).toBe(fn2)
+  })
+
+  it("should wrap object in a function and append", () => {
+    const obj = { color: "blue" }
+    const result = chainOptions(obj, [])
+    expect(result).toHaveLength(1)
+    expect(result[0]?.()).toEqual(obj)
+  })
+
+  it("should return empty array when no defaults and undefined opts", () => {
+    const result = chainOptions(undefined, [])
+    expect(result).toEqual([])
+  })
+
+  it("should not mutate the defaults array", () => {
+    const defaults = [() => ({})]
+    const fn = () => ({ a: 1 })
+    const result = chainOptions(fn, defaults)
+    expect(defaults).toHaveLength(1)
+    expect(result).toHaveLength(2)
+  })
+})
+
+// --------------------------------------------------------
+// createStaticsEnhancers
+// --------------------------------------------------------
+describe("createStaticsEnhancers", () => {
+  it("should assign options to context", () => {
+    const context: Record<string, any> = {}
+    createStaticsEnhancers({
+      context,
+      options: { theme: "dark", variant: "primary" },
+    })
+    expect(context).toEqual({ theme: "dark", variant: "primary" })
+  })
+
+  it("should not modify context when options is empty", () => {
+    const context: Record<string, any> = { existing: true }
+    createStaticsEnhancers({ context, options: {} })
+    expect(context).toEqual({ existing: true })
+  })
+
+  it("should merge with existing context properties", () => {
+    const context: Record<string, any> = { existing: true }
+    createStaticsEnhancers({ context, options: { newProp: "value" } })
+    expect(context).toEqual({ existing: true, newProp: "value" })
+  })
+})
+
+// --------------------------------------------------------
+// calculateHocsFuncs
+// --------------------------------------------------------
+describe("calculateHocsFuncs", () => {
+  it("should return empty array for empty options", () => {
+    const result = calculateHocsFuncs({})
+    expect(result).toEqual([])
+  })
+
+  it("should filter out non-function values", () => {
+    const fn = (x: any) => x
+    const result = calculateHocsFuncs({ a: fn, b: "string", c: 123 })
+    expect(result).toHaveLength(1)
+    expect(result[0]).toBe(fn)
+  })
+
+  it("should reverse the order of functions", () => {
+    const fn1 = (x: any) => x
+    const fn2 = (x: any) => x
+    const result = calculateHocsFuncs({ a: fn1, b: fn2 })
+    expect(result[0]).toBe(fn2)
+    expect(result[1]).toBe(fn1)
+  })
+
+  it("should return empty array for undefined input", () => {
+    const result = calculateHocsFuncs(undefined as any)
+    expect(result).toEqual([])
+  })
+})

package/src/attrs.ts

@@ -0,0 +1,126 @@
+import { compose, hoistNonReactStatics, omit, pick } from "@pyreon/ui-core"
+import { attrsHoc } from "./hoc"
+import type { AttrsComponent as AttrsComponentType } from "./types/AttrsComponent"
+import type { Configuration, ExtendedConfiguration } from "./types/configuration"
+import type { InitAttrsComponent } from "./types/InitAttrsComponent"
+import { calculateChainOptions } from "./utils/attrs"
+import { chainOptions } from "./utils/chaining"
+import { calculateHocsFuncs } from "./utils/compose"
+import { createStaticsEnhancers } from "./utils/statics"
+
+/**
+ * Clones the current configuration and merges new options, then creates a
+ * fresh component. This makes the chaining API immutable — each `.attrs()`
+ * / `.config()` / `.statics()` call returns a brand-new component with an
+ * updated configuration rather than mutating the existing one.
+ */
+type CloneAndEnhance = (
+  defaultOpts: Configuration,
+  opts: Partial<ExtendedConfiguration>,
+) => ReturnType<typeof attrsComponent>
+
+const cloneAndEnhance: CloneAndEnhance = (defaultOpts, opts) =>
+  attrsComponent({
+    ...defaultOpts,
+    ...(opts.name ? { name: opts.name } : undefined),
+    ...(opts.component ? { component: opts.component } : undefined),
+    attrs: chainOptions(opts.attrs, defaultOpts.attrs),
+    filterAttrs: [...(defaultOpts.filterAttrs ?? []), ...(opts.filterAttrs ?? [])],
+    priorityAttrs: chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
+    statics: { ...defaultOpts.statics, ...opts.statics },
+    compose: { ...defaultOpts.compose, ...opts.compose },
+  } as Parameters<typeof attrsComponent>[0])
+
+/**
+ * Core factory that builds an attrs-enhanced Pyreon component.
+ *
+ * Creates a plain ComponentFn that:
+ * 1. Wraps the original with attrsHoc (default props) + user HOCs from `.compose()`.
+ * 2. Filters out internal props listed in `filterAttrs`.
+ * 3. Attaches `data-attrs` attribute in development for debugging.
+ *
+ * Then adds chaining methods (`.attrs()`, `.config()`, `.compose()`, `.statics()`)
+ * as static properties — each calls `cloneAndEnhance` to produce a new component.
+ *
+ * In Pyreon, there is no forwardRef — ref flows as a normal prop.
+ * Components are plain functions that run once per mount.
+ */
+const attrsComponent: InitAttrsComponent = (options) => {
+  const componentName = options.name ?? options.component.displayName ?? options.component.name
+
+  const RenderComponent = options.component
+
+  // Build the HOC chain: attrsHoc is always first (resolves default props),
+  // followed by user-composed HOCs in reverse order (outermost wraps first).
+  const hocsFuncs = [attrsHoc(options), ...calculateHocsFuncs(options.compose)]
+
+  // The inner component receives already-computed props from the HOC chain.
+  // It handles prop filtering and final rendering.
+  const EnhancedComponent = (props: Record<string, any>) => {
+    const needsFiltering = options.filterAttrs && options.filterAttrs.length > 0
+
+    const filteredProps = needsFiltering ? omit(props, options.filterAttrs) : props
+
+    const finalProps =
+      process.env.NODE_ENV !== "production"
+        ? { ...filteredProps, "data-attrs": componentName }
+        : filteredProps
+
+    return RenderComponent(finalProps)
+  }
+
+  // Apply the full HOC chain: compose(attrsHoc, ...userHocs)(EnhancedComponent)
+  const AttrsComponent: AttrsComponentType = compose(...hocsFuncs)(EnhancedComponent)
+
+  AttrsComponent.IS_ATTRS = true
+  AttrsComponent.displayName = componentName
+  AttrsComponent.meta = {}
+
+  // Copy static properties from the original component.
+  hoistNonReactStatics(AttrsComponent, options.component)
+
+  // Populate `component.meta` with user-defined statics from `.statics()`.
+  createStaticsEnhancers({
+    context: AttrsComponent.meta,
+    options: options.statics,
+  })
+
+  // ─── Chaining Methods ──────────────────────────────────
+  // Each method creates a new component via cloneAndEnhance.
+  // The original component is never mutated.
+  Object.assign(AttrsComponent, {
+    attrs: (attrs: any, { priority, filter }: any = {}) => {
+      const result: Record<string, any> = {}
+
+      if (filter) {
+        result.filterAttrs = filter
+      }
+
+      if (priority) {
+        result.priorityAttrs = attrs as ExtendedConfiguration["priorityAttrs"]
+
+        return cloneAndEnhance(options, result)
+      }
+
+      result.attrs = attrs as ExtendedConfiguration["attrs"]
+
+      return cloneAndEnhance(options, result)
+    },
+
+    config: (opts: any = {}) => {
+      const result = pick(opts)
+
+      return cloneAndEnhance(options, result)
+    },
+
+    compose: (opts: any) => cloneAndEnhance(options, { compose: opts }),
+
+    statics: (opts: any) => cloneAndEnhance(options, { statics: opts }),
+
+    getDefaultAttrs: (props: any) => calculateChainOptions(options.attrs)([props]),
+  })
+
+  return AttrsComponent
+}
+
+export default attrsComponent

package/src/hoc/attrsHoc.ts

@@ -0,0 +1,60 @@
+import type { Configuration } from "../types/configuration"
+import type { ComponentFn } from "../types/utils"
+import { calculateChainOptions, removeUndefinedProps } from "../utils/attrs"
+
+export type AttrsStyleHOC = ({
+  attrs,
+  priorityAttrs,
+}: Pick<Configuration, "attrs" | "priorityAttrs">) => (
+  WrappedComponent: ComponentFn<any>,
+) => ComponentFn<any>
+
+/**
+ * Creates the core HOC that computes default props from the `.attrs()` chain.
+ *
+ * This is always the outermost HOC in the compose chain, so it runs first.
+ * It resolves both priority and normal attrs callbacks, then merges them
+ * with the consumer's explicit props following this precedence:
+ *
+ *   priorityAttrs < normalAttrs < explicit props  (last wins)
+ *
+ * In Pyreon, components are plain functions — no forwardRef needed.
+ * The ref flows as a normal prop through the chain.
+ */
+const createAttrsHOC: AttrsStyleHOC = ({ attrs, priorityAttrs }) => {
+  // Pre-build the chain reducers once (not per render).
+  const calculateAttrs = calculateChainOptions(attrs)
+  const calculatePriorityAttrs = calculateChainOptions(priorityAttrs)
+
+  const attrsHoc = (WrappedComponent: ComponentFn<any>) => {
+    const HOCComponent: ComponentFn<any> = (props) => {
+      // Strip undefined values so they don't shadow defaults from attrs callbacks.
+      const filteredProps = removeUndefinedProps(props)
+
+      // 1. Resolve priority attrs (lowest precedence defaults).
+      const prioritizedAttrs = calculatePriorityAttrs([filteredProps])
+      // 2. Resolve normal attrs — these see priority + explicit props as input.
+      const finalAttrs = calculateAttrs([
+        {
+          ...prioritizedAttrs,
+          ...filteredProps,
+        },
+      ])
+
+      // 3. Merge: priority < normal attrs < explicit props (last wins).
+      const finalProps = {
+        ...prioritizedAttrs,
+        ...finalAttrs,
+        ...filteredProps,
+      }
+
+      return WrappedComponent(finalProps)
+    }
+
+    return HOCComponent
+  }
+
+  return attrsHoc
+}
+
+export default createAttrsHOC

package/src/hoc/index.ts

@@ -0,0 +1,3 @@
+import attrsHoc from "./attrsHoc"
+
+export { attrsHoc }

package/src/index.ts

@@ -0,0 +1,26 @@
+import type { Attrs } from "./init"
+import attrs from "./init"
+import type { IsAttrsComponent } from "./isAttrsComponent"
+import isAttrsComponent from "./isAttrsComponent"
+import type { AttrsComponent } from "./types/AttrsComponent"
+import type { AttrsCb } from "./types/attrs"
+import type { AttrsComponentType, ConfigAttrs } from "./types/config"
+import type { ComposeParam, GenericHoc } from "./types/hoc"
+import type { ComponentFn, ElementType, TObj } from "./types/utils"
+
+export type {
+  Attrs,
+  AttrsCb,
+  AttrsComponent,
+  AttrsComponentType,
+  ComponentFn,
+  ComposeParam,
+  ConfigAttrs,
+  ElementType,
+  GenericHoc,
+  IsAttrsComponent,
+  TObj,
+}
+
+export { attrs, isAttrsComponent }
+export default attrs

package/src/init.ts

@@ -0,0 +1,59 @@
+import { isEmpty } from "@pyreon/ui-core"
+import attrsComponent from "./attrs"
+import type { InitAttrsComponent } from "./types/InitAttrsComponent"
+import type { ElementType } from "./types/utils"
+
+/**
+ * Public entry point for creating an attrs-enhanced component.
+ *
+ * ```tsx
+ * const Button = attrs({ name: 'Button', component: Element })
+ *   .attrs({ tag: 'button' })
+ *   .attrs<{ primary?: boolean }>(({ primary }) => ({
+ *     backgroundColor: primary ? 'blue' : 'gray',
+ *   }))
+ * ```
+ */
+export type Attrs = <C extends ElementType>({
+  name,
+  component,
+}: {
+  name: string
+  component: C
+}) => ReturnType<InitAttrsComponent<C>>
+
+const attrs: Attrs = ({ name, component }) => {
+  // Validate required params in development — fail fast with clear errors.
+  if (process.env.NODE_ENV !== "production") {
+    type Errors = Partial<{
+      component: string
+      name: string
+    }>
+
+    const errors: Errors = {}
+    if (!component) {
+      errors.component = "Parameter `component` is missing in params!"
+    }
+
+    if (!name) {
+      errors.name = "Parameter `name` is missing in params!"
+    }
+
+    if (!isEmpty(errors)) {
+      throw Error(JSON.stringify(errors))
+    }
+  }
+
+  // Bootstrap with empty configuration — all chains start from scratch.
+  return attrsComponent({
+    name,
+    component,
+    attrs: [],
+    priorityAttrs: [],
+    filterAttrs: [],
+    compose: {},
+    statics: {},
+  })
+}
+
+export default attrs

package/src/isAttrsComponent.ts

@@ -0,0 +1,16 @@
+export type IsAttrsComponent = <T>(component: T) => boolean
+
+/** Runtime type guard — checks if a component was created by `attrs()`. */
+const isAttrsComponent: IsAttrsComponent = (component) => {
+  if (
+    component &&
+    (typeof component === "object" || typeof component === "function") &&
+    Object.hasOwn(component as object, "IS_ATTRS")
+  ) {
+    return true
+  }
+
+  return false
+}
+
+export default isAttrsComponent

package/src/types/AttrsComponent.ts

@@ -0,0 +1,83 @@
+import type { VNode } from "@pyreon/core"
+import type { AttrsCb } from "./attrs"
+import type { ConfigAttrs } from "./config"
+import type { ComposeParam } from "./hoc"
+import type { ElementType, ExtractProps, MergeTypes, TObj } from "./utils"
+
+/**
+ * Props passed to the inner enhanced component.
+ * In Pyreon there's no forwardRef — ref flows as a normal prop.
+ */
+export type InnerComponentProps = {
+  "data-attrs"?: string | undefined
+}
+
+/**
+ * @param OA   Origin component props params.
+ * @param EA   Extended prop types
+ * @param S    Defined statics
+ * @param HOC  High-order components
+ * @param DFP  Calculated final component props
+ */
+export interface AttrsComponent<
+  C extends ElementType = ElementType,
+  // original component props
+  OA extends TObj = {},
+  // extended component props
+  EA extends TObj = {},
+  // statics
+  S extends TObj = {},
+  // hocs
+  HOC extends TObj = {},
+  // calculated final props
+  DFP extends Record<string, any> = MergeTypes<[OA, EA]>,
+> {
+  // The component is callable — Pyreon components are plain functions
+  (props: DFP): VNode | null
+
+  // CONFIG chaining method
+  config: <NC extends ElementType | unknown = unknown>({
+    name,
+    component: NC,
+    DEBUG,
+  }: ConfigAttrs<NC>) => NC extends ElementType
+    ? AttrsComponent<NC, ExtractProps<NC>, EA, S, HOC>
+    : AttrsComponent<C, OA, EA, S, HOC>
+
+  // ATTRS chaining method
+  attrs: <P extends TObj | unknown = unknown>(
+    param: P extends TObj ? Partial<DFP & P> | AttrsCb<DFP & P> : Partial<DFP> | AttrsCb<DFP>,
+    config?: Partial<{
+      priority: boolean
+      filter: unknown extends P ? string[] : (keyof (EA & P))[]
+    }>,
+  ) => P extends TObj
+    ? AttrsComponent<C, OA, MergeTypes<[EA, P]>, S, HOC>
+    : AttrsComponent<C, OA, EA, S, HOC>
+
+  // COMPOSE chaining method
+  compose: <P extends ComposeParam>(
+    param: P,
+  ) => P extends TObj
+    ? AttrsComponent<C, OA, EA, S, MergeTypes<[HOC, P]>>
+    : AttrsComponent<C, OA, EA, S, HOC>
+
+  // STATICS chaining method
+  statics: <P extends TObj | unknown = unknown>(
+    param: P,
+  ) => P extends TObj
+    ? AttrsComponent<C, OA, EA, MergeTypes<[S, P]>, HOC>
+    : AttrsComponent<C, OA, EA, S, HOC>
+
+  /** Access to all defined statics on the component. */
+  meta: S
+
+  getDefaultAttrs: (props: TObj) => TObj
+
+  readonly $$originTypes: OA
+  readonly $$extendedTypes: EA
+  readonly $$types: DFP
+
+  IS_ATTRS: true
+  displayName: string
+}

package/src/types/InitAttrsComponent.ts

@@ -0,0 +1,19 @@
+import type { AttrsComponent } from "./AttrsComponent"
+import type { Configuration } from "./configuration"
+import type { ElementType, ExtractProps } from "./utils"
+
+/**
+ * Type of the internal `attrsComponent` factory function.
+ * Takes a full Configuration and returns an AttrsComponent whose
+ * original props (OA) are extracted from the component type C,
+ * with all extension slots (EA, S, HOC) starting empty.
+ */
+export type InitAttrsComponent<C extends ElementType = ElementType> = (
+  params: Configuration<C>,
+) => AttrsComponent<
+  C,
+  ExtractProps<C>, // OA — original component props
+  {}, // EA — extended props (empty initially)
+  {}, // S  — statics (empty initially)
+  {} //  HOC — composed HOCs (empty initially)
+>

package/src/types/attrs.ts

@@ -0,0 +1,2 @@
+/** Callback form of `.attrs()` — receives current props and returns partial overrides. */
+export type AttrsCb<A> = (props: Partial<A>) => Partial<A>

package/src/types/config.ts

@@ -0,0 +1,13 @@
+import type { ElementType } from "./utils"
+
+/** A component that has been enhanced by attrs — identified by the `IS_ATTRS` marker. */
+export type AttrsComponentType = ElementType & {
+  IS_ATTRS: true
+}
+
+/** Parameters accepted by the `.config()` chaining method. */
+export type ConfigAttrs<C extends ElementType | unknown> = Partial<{
+  name: string
+  component: C
+  DEBUG: boolean
+}>