@pyreon/attrs 0.11.1 → 0.11.2

package/src/types/configuration.ts

@@ -0,0 +1,40 @@
+import type { ElementType, TFn } from "./utils"
+
+export type OptionFunc = (...arg: unknown[]) => Record<string, unknown>
+
+export type InitConfiguration<C> = {
+  name?: string | undefined
+  component: C
+}
+
+/**
+ * Internal configuration accumulated across the chaining API.
+ * Arrays hold the full chain — each `.attrs()` call appends to these.
+ */
+export type Configuration<C = ElementType | unknown> = InitConfiguration<C> & {
+  DEBUG?: boolean | undefined
+  /** Chain of default-props callbacks (resolved in order, later wins). */
+  attrs: OptionFunc[]
+  /** Chain of priority-props callbacks (resolved before `attrs`, can be overridden by both). */
+  priorityAttrs: OptionFunc[]
+  /** Prop names to omit before passing to the underlying component. */
+  filterAttrs: string[]
+  /** Named HOCs — set to null/false to remove from chain. */
+  compose: Record<string, TFn | null | undefined | false>
+  /** Metadata accessible via `Component.meta`. */
+  statics: Record<string, any>
+} & Record<string, any>
+
+/**
+ * Single-item variant of Configuration — represents what a single
+ * `.attrs()` / `.config()` call contributes (one function, not an array).
+ * Used by `cloneAndEnhance` to merge into the accumulated Configuration.
+ */
+export type ExtendedConfiguration<C = ElementType | unknown> = InitConfiguration<C> & {
+  DEBUG?: boolean | undefined
+  attrs: OptionFunc
+  priorityAttrs: OptionFunc
+  filterAttrs: string[]
+  compose: Record<string, TFn | null | undefined | false>
+  statics: Record<string, any>
+} & Record<string, any>

package/src/types/hoc.ts

@@ -0,0 +1,10 @@
+import type { ElementType } from "./utils"
+
+export type GenericHoc = (component: ElementType) => ElementType
+
+/**
+ * Parameters for `.compose()` — a record of named HOCs.
+ * Setting a key to `null`, `undefined`, or `false` removes a
+ * previously defined HOC from the chain.
+ */
+export type ComposeParam = Record<string, GenericHoc | null | undefined | false>

package/src/types/utils.ts

@@ -0,0 +1,106 @@
+import type { VNodeChild } from "@pyreon/core"
+
+// ─── Base Types ───────────────────────────────────────────────
+
+export type TObj = Record<string, unknown>
+export type TFn = (...args: any) => any
+export type CallBackParam = TObj | TFn
+export type DisplayName = string
+
+/**
+ * A Pyreon component function that accepts additional static properties.
+ * Aligned with @pyreon/core's ComponentFn — returns VNodeChild (not just VNode | null)
+ * to support components returning strings, numbers, undefined, etc.
+ */
+export type ComponentFn<P = any> = ((props: P) => VNodeChild) & Partial<Record<string, any>>
+
+/**
+ * An element type — either a Pyreon component function or an intrinsic tag string.
+ */
+export type ElementType<T extends TObj | unknown = any> = ComponentFn<T>
+
+export type ValueOf<T> = T[keyof T]
+
+export type ArrayOfValues<T> = T[keyof T]
+
+export type ArrayOfKeys<T> = keyof T[]
+
+/**
+ * A HOC that wraps a component and merges additional props `P`
+ * with the wrapped component's own props.
+ */
+export type SimpleHoc<P extends Record<string, unknown> = Record<string, unknown>> = <
+  T extends ComponentFn<any>,
+>(
+  WrappedComponent: T,
+) => ComponentFn<MergeTypes<[P, ExtractProps<T>]>>
+
+/** Maps each key to `never` if the value is null, undefined, or false. */
+type IsFalseOrNullable<T> = T extends null | undefined | false ? never : true
+export type NullableKeys<T> = { [K in keyof T]: IsFalseOrNullable<T[K]> }
+
+/** Unwraps a callback to its return type, or returns the object as-is. */
+export type ReturnCbParam<P extends TFn | TObj> = P extends TFn ? ReturnType<P> : P
+
+// ─── MergeTypes ───────────────────────────────────────────────
+//
+// Merges a tuple of object types left-to-right (like Object.assign),
+// then strips keys whose values resolved to `never`, `null`, or `undefined`.
+//
+// Usage: MergeTypes<[BaseProps, ExtendedProps, OverrideProps]>
+//
+// This is the backbone of the chaining API — each `.attrs<P>()`
+// call produces MergeTypes<[PreviousProps, P]> so later definitions
+// override earlier ones while preserving the rest.
+// ──────────────────────────────────────────────────────────────
+
+/**
+ * Forces TypeScript to expand/flatten a type for better IDE display.
+ * Short-circuits for `any` — the mapped type would turn `any` into
+ * `{ [x: string]: any; [x: number]: any; [x: symbol]: any }`, losing
+ * its identity as `any` and breaking downstream type checks.
+ */
+type Id<T> = 0 extends 1 & T ? T : T extends infer U ? { [K in keyof U]: U[K] } : never
+
+/**
+ * Strips keys whose values are `never`, `null`, or `undefined`.
+ * Uses tuple wrapping `[T[P]] extends [never]` to avoid distribution
+ * over union types (a bare `T[P] extends never` would incorrectly
+ * match union members).
+ *
+ * Short-circuits for `any` — the `as` clause in mapped types loses
+ * index signatures, which would turn `any` into an empty type.
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false
+
+type ExtractNullableKeys<T> = 0 extends 1 & T
+  ? T
+  : {
+      [P in keyof T as IsAny<T[P]> extends true
+        ? P
+        : [T[P]] extends [never]
+          ? never
+          : [T[P]] extends [null | undefined]
+            ? never
+            : P]: T[P]
+    }
+
+/** Merges two types: keeps all keys from L that don't exist in R, then adds all of R. */
+type SpreadTwo<L, R> = Id<Pick<L, Exclude<keyof L, keyof R>> & R>
+
+/** Recursively spreads a tuple of types left-to-right. */
+type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R]
+  ? SpreadTwo<L, Spread<R>>
+  : unknown
+
+/** Recursively checks whether any element in the tuple is `any`. */
+type _HasAny<A> = A extends [infer L, ...infer R] ? (0 extends 1 & L ? true : _HasAny<R>) : false
+
+export type MergeTypes<A extends readonly [...any]> =
+  _HasAny<A> extends true ? any : ExtractNullableKeys<Spread<A>>
+
+// ─── ExtractProps ─────────────────────────────────────────────
+
+/** Extracts the props type from a Pyreon component function. */
+export type ExtractProps<TComponentOrTProps> =
+  TComponentOrTProps extends ComponentFn<infer TProps> ? TProps : TComponentOrTProps

package/src/utils/attrs.ts

@@ -0,0 +1,40 @@
+import { isEmpty } from "@pyreon/ui-core"
+
+/**
+ * Strips keys with `undefined` values from a props object.
+ * This prevents undefined consumer props from overriding defaults
+ * computed by `.attrs()` callbacks. Only explicitly set values
+ * (including `null`) should override defaults.
+ */
+type RemoveUndefinedProps = <T extends Record<string, any>>(
+  props: T,
+) => { [I in keyof T as T[I] extends undefined ? never : I]: T[I] }
+
+export const removeUndefinedProps = (<T extends Record<string, any>>(props: T) =>
+  Object.keys(props).reduce<Record<string, unknown>>((acc, key) => {
+    const currentValue = props[key]
+    if (currentValue !== undefined) acc[key] = currentValue
+    return acc
+  }, {})) as RemoveUndefinedProps
+
+/**
+ * Reduces an array of option functions (from chained `.attrs()` calls)
+ * into a single merged result. Each function is called with `args`
+ * (typically the current props) and its return value is merged
+ * left-to-right via Object.assign — so later `.attrs()` calls
+ * override earlier ones.
+ *
+ * Returns a curried function: first call binds the chain, second
+ * call provides the arguments and executes the reduction.
+ */
+type OptionFunc<A> = (...arg: A[]) => Record<string, unknown>
+type CalculateChainOptions = <A>(
+  options?: OptionFunc<A>[],
+) => (args: A[]) => ReturnType<OptionFunc<A>>
+
+export const calculateChainOptions: CalculateChainOptions = (options) => (args) => {
+  const result = {}
+  if (!options || isEmpty(options)) return result
+
+  return options.reduce((acc, item) => Object.assign(acc, item(...args)), {})
+}

package/src/utils/chaining.ts

@@ -0,0 +1,21 @@
+type Func = (...args: any) => Record<string, unknown>
+type Obj = Record<string, unknown>
+
+/**
+ * Appends a new attrs option to the existing chain of option functions.
+ *
+ * The `.attrs()` API accepts either an object or a callback. This function
+ * normalizes both forms into a function (objects are wrapped in `() => obj`)
+ * and appends to the existing array. The array is cloned so each chained
+ * component gets its own copy — maintaining immutability across the chain.
+ */
+type ChainOptions = (opts: Obj | Func | undefined, defaultOpts: Func[]) => Func[]
+
+export const chainOptions: ChainOptions = (opts, defaultOpts = []) => {
+  const result = [...defaultOpts]
+
+  if (typeof opts === "function") result.push(opts)
+  else if (typeof opts === "object") result.push(() => opts)
+
+  return result
+}

package/src/utils/collection.ts

@@ -0,0 +1,14 @@
+/**
+ * Filters out keys with `null`, `undefined`, or `false` values.
+ * Used to clean compose config — setting a HOC to `false`/`null` removes it.
+ */
+type RemoveNullableValues = (obj: Record<string, any>) => Record<string, any>
+export const removeNullableValues: RemoveNullableValues = (obj) => {
+  const result: Record<string, any> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (v != null && v !== false) {
+      result[k] = v
+    }
+  }
+  return result
+}

package/src/utils/compose.ts

@@ -0,0 +1,14 @@
+/**
+ * Extracts HOC functions from the `.compose()` configuration and reverses
+ * them for correct application order. Setting a key to `null`, `undefined`,
+ * or `false` removes a previously defined HOC — only actual functions are kept.
+ *
+ * The reversal is needed because `compose(a, b, c)(Component)` applies as
+ * `a(b(c(Component)))`, so the last-defined HOC should wrap innermost.
+ */
+type CalculateHocsFuncs = (options: Record<string, any>) => ((arg: any) => any)[]
+
+export const calculateHocsFuncs: CalculateHocsFuncs = (options = {}) =>
+  Object.values(options)
+    .filter((item) => typeof item === "function")
+    .reverse()

package/src/utils/statics.ts

@@ -0,0 +1,16 @@
+import { isEmpty } from "@pyreon/ui-core"
+
+/**
+ * Copies user-defined statics from `.statics()` into the component's
+ * `meta` object. These are accessible at `Component.meta.myStatic`.
+ */
+type CreateStaticsEnhancers = (params: {
+  context: Record<string, any>
+  options: Record<string, any>
+}) => void
+
+export const createStaticsEnhancers: CreateStaticsEnhancers = ({ context, options }) => {
+  if (!isEmpty(options)) {
+    Object.assign(context, options)
+  }
+}