@pyreon/attrs 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Vit Bokisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @pyreon/attrs
+
+Immutable, chainable default-props factory for Pyreon components.
+
+Think of styled-components' `.attrs()` as a standalone, type-safe composition system. Define default props, swap base components, attach HOCs, and add metadata — all through an immutable chain where every call returns a new component.
+
+## Features
+
+- **Immutable chaining** — every method returns a new component, never mutates the original
+- **Props merge order** — `priorityAttrs` > `attrs` > explicit props, with full control over precedence
+- **Prop filtering** — strip internal props before they reach the DOM
+- **HOC composition** — named HOCs via `.compose()` with selective removal
+- **Static metadata** — attach and access custom data via `.statics()` / `.meta`
+- **TypeScript inference** — generics accumulate through the chain
+
+## Installation
+
+```bash
+bun add @pyreon/attrs
+```
+
+## Quick Start
+
+```ts
+import attrs from '@pyreon/attrs'
+import { Element } from '@pyreon/elements'
+
+const Button = attrs({ name: 'Button', component: Element })
+  .attrs({ tag: 'button', alignX: 'center', alignY: 'center' })
+
+// Renders Element with tag="button", alignX="center", alignY="center"
+Button({ label: 'Click me' })
+
+// Explicit props override attrs defaults
+Button({ tag: 'a', label: 'Link button' })
+```
+
+## API
+
+### attrs(options)
+
+Creates an attrs-enhanced component.
+
+```ts
+const Component = attrs({
+  name: 'ComponentName',    // required — sets displayName
+  component: BaseComponent, // required — the Pyreon component to wrap
+})
+```
+
+### .attrs(props | callback, options?)
+
+Add default props. Can be called multiple times — defaults stack left-to-right.
+
+```ts
+// Object form — static defaults
+Button.attrs({ tag: 'button' })
+
+// Callback form — computed defaults based on current props
+Button.attrs((props) => ({
+  'aria-label': props.label,
+}))
+
+// Priority — resolved before regular attrs, cannot be overridden by explicit props
+Button.attrs({ tag: 'button' }, { priority: true })
+
+// Filter — remove props before passing to the underlying component
+Button.attrs({}, { filter: ['internalFlag', 'variant'] })
+```
+
+**Props merge order:**
+
+```text
+priorityAttrs (highest) → attrs → explicit props (lowest for priority, highest for regular)
+```
+
+For regular attrs, explicit props win. For priority attrs, the priority value wins.
+
+### .config(options)
+
+Reconfigure the component. Returns a new component instance.
+
+```ts
+// Rename
+Button.config({ name: 'PrimaryButton' })
+
+// Swap the base component
+Button.config({ component: AnotherComponent })
+
+// Enable debug mode — adds data-attrs attribute in development
+Button.config({ DEBUG: true })
+```
+
+### .compose(hocs)
+
+Attach named Higher-Order Components. Applied in declaration order.
+
+```ts
+const Enhanced = Button.compose({
+  withTheme: (Component) => (props) => Component({ ...props, themed: true }),
+  withTracking: trackingHoc,
+})
+
+// Remove a specific HOC from the chain
+const WithoutTracking = Enhanced.compose({ withTracking: null })
+```
+
+### .statics(metadata)
+
+Attach metadata accessible via the `.meta` property.
+
+```ts
+const Button = attrs({ name: 'Button', component: Element })
+  .statics({ category: 'action', sizes: ['sm', 'md', 'lg'] })
+
+Button.meta.category // => 'action'
+Button.meta.sizes    // => ['sm', 'md', 'lg']
+```
+
+### isAttrsComponent(value)
+
+Runtime type guard.
+
+```ts
+import { isAttrsComponent } from '@pyreon/attrs'
+
+isAttrsComponent(Button) // => true
+isAttrsComponent('div')  // => false
+```
+
+### getDefaultAttrs()
+
+Retrieve the computed default props for a component.
+
+```ts
+Button.getDefaultAttrs() // => { tag: 'button', alignX: 'center', ... }
+```
+
+## TypeScript
+
+Each `.attrs<P>()` call adds `P` to the component's prop types through `MergeTypes`:
+
+```ts
+const Base = attrs({ name: 'Base', component: Element })
+
+const Typed = Base
+  .attrs<{ variant: 'primary' | 'secondary' }>({ variant: 'primary' })
+  .attrs<{ size?: 'sm' | 'md' | 'lg' }>({})
+
+// Typed accepts: Element props + { variant, size? }
+Typed({ variant: 'secondary', size: 'lg', label: 'Hello' })
+```
+
+Access the accumulated types via type-only properties:
+
+```ts
+type AllProps = typeof Typed.$$types
+type OriginalProps = typeof Typed.$$originTypes
+type ExtendedProps = typeof Typed.$$extendedTypes
+```
+
+## Peer Dependencies
+
+| Package | Version |
+| ------- | ------- |
+| @pyreon/core | >= 0.0.1 |
+| @pyreon/ui-core | >= 0.0.1 |
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,157 @@
+import { VNode } from "@pyreon/core";
+
+//#region src/types/attrs.d.ts
+/** Callback form of `.attrs()` — receives current props and returns partial overrides. */
+type AttrsCb<A> = (props: Partial<A>) => Partial<A>;
+//#endregion
+//#region src/types/utils.d.ts
+type TObj = Record<string, unknown>;
+type TFn = (...args: any) => any;
+/**
+ * A Pyreon component function that accepts additional static properties.
+ * In Pyreon, components are plain functions: (props: P) => VNode | null.
+ */
+type ComponentFn<P = any> = ((props: P) => VNode | null) & Partial<Record<string, any>>;
+/**
+ * An element type — either a Pyreon component function or an intrinsic tag string.
+ */
+type ElementType<T extends TObj | unknown = any> = ComponentFn<T>;
+/**
+ * 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;
+type MergeTypes<A extends readonly [...any]> = _HasAny<A> extends true ? any : ExtractNullableKeys<Spread<A>>;
+/** Extracts the props type from a Pyreon component function. */
+type ExtractProps<TComponentOrTProps> = TComponentOrTProps extends ComponentFn<infer TProps> ? TProps : TComponentOrTProps;
+//#endregion
+//#region src/types/config.d.ts
+/** A component that has been enhanced by attrs — identified by the `IS_ATTRS` marker. */
+type AttrsComponentType = ElementType & {
+  IS_ATTRS: true;
+};
+/** Parameters accepted by the `.config()` chaining method. */
+type ConfigAttrs<C extends ElementType | unknown> = Partial<{
+  name: string;
+  component: C;
+  DEBUG: boolean;
+}>;
+//#endregion
+//#region src/types/hoc.d.ts
+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.
+ */
+type ComposeParam = Record<string, GenericHoc | null | undefined | false>;
+//#endregion
+//#region src/types/AttrsComponent.d.ts
+/**
+ * @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
+ */
+interface AttrsComponent<C extends ElementType = ElementType, OA extends TObj = TObj, EA extends TObj = TObj, S extends TObj = TObj, HOC extends TObj = TObj, DFP extends Record<string, any> = MergeTypes<[OA, EA]>> {
+  (props: DFP): VNode | null;
+  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: <P extends TObj | unknown = unknown>(param: P extends TObj ? Partial<MergeTypes<[DFP, P]>> | AttrsCb<MergeTypes<[DFP, P]>> : Partial<DFP> | AttrsCb<DFP>, config?: Partial<{
+    priority: boolean;
+    filter: unknown extends P ? string[] : (keyof MergeTypes<[EA, P]>)[];
+  }>) => P extends TObj ? AttrsComponent<C, OA, MergeTypes<[EA, P]>, S, HOC> : AttrsComponent<C, OA, EA, S, HOC>;
+  compose: <P extends ComposeParam>(param: P) => P extends TObj ? AttrsComponent<C, OA, EA, S, MergeTypes<[HOC, P]>> : AttrsComponent<C, OA, EA, S, HOC>;
+  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;
+}
+//#endregion
+//#region src/types/configuration.d.ts
+type OptionFunc = (...arg: unknown[]) => Record<string, unknown>;
+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.
+ */
+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>;
+//#endregion
+//#region src/types/InitAttrsComponent.d.ts
+/**
+ * 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.
+ */
+type InitAttrsComponent<C extends ElementType = ElementType> = (params: Configuration<C>) => AttrsComponent<C, ExtractProps<C>, // OA — original component props
+TObj, // EA — extended props (empty initially)
+TObj, // S  — statics (empty initially)
+TObj>;
+//#endregion
+//#region src/init.d.ts
+/**
+ * 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',
+ *   }))
+ * ```
+ */
+type Attrs = <C extends ElementType>({
+  name,
+  component
+}: {
+  name: string;
+  component: C;
+}) => ReturnType<InitAttrsComponent<C>>;
+declare const attrs: Attrs;
+//#endregion
+//#region src/isAttrsComponent.d.ts
+type IsAttrsComponent = <T>(component: T) => boolean;
+/** Runtime type guard — checks if a component was created by `attrs()`. */
+declare const isAttrsComponent: IsAttrsComponent;
+//#endregion
+export { type Attrs, type AttrsCb, type AttrsComponent, type AttrsComponentType, type ComponentFn, type ComposeParam, type ConfigAttrs, type ElementType, type GenericHoc, type IsAttrsComponent, type TObj, attrs, attrs as default, isAttrsComponent };
+//# sourceMappingURL=index2.d.ts.map

package/lib/index.js

@@ -0,0 +1,177 @@
+import { compose, hoistNonReactStatics, isEmpty, omit, pick } from "@pyreon/ui-core";
+
+//#region src/utils/attrs.ts
+const removeUndefinedProps = ((props) => Object.keys(props).reduce((acc, key) => {
+	const currentValue = props[key];
+	if (currentValue !== void 0) acc[key] = currentValue;
+	return acc;
+}, {}));
+const calculateChainOptions = (options) => (args) => {
+	const result = {};
+	if (!options || isEmpty(options)) return result;
+	return options.reduce((acc, item) => Object.assign(acc, item(...args)), {});
+};
+
+//#endregion
+//#region src/hoc/attrsHoc.ts
+/**
+* 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 = ({ attrs, priorityAttrs }) => {
+	const calculateAttrs = calculateChainOptions(attrs);
+	const calculatePriorityAttrs = calculateChainOptions(priorityAttrs);
+	const attrsHoc = (WrappedComponent) => {
+		const HOCComponent = (props) => {
+			const filteredProps = removeUndefinedProps(props);
+			const prioritizedAttrs = calculatePriorityAttrs([filteredProps]);
+			const finalAttrs = calculateAttrs([{
+				...prioritizedAttrs,
+				...filteredProps
+			}]);
+			return WrappedComponent({
+				...prioritizedAttrs,
+				...finalAttrs,
+				...filteredProps
+			});
+		};
+		return HOCComponent;
+	};
+	return attrsHoc;
+};
+
+//#endregion
+//#region src/utils/chaining.ts
+const chainOptions = (opts, defaultOpts = []) => {
+	const result = [...defaultOpts];
+	if (typeof opts === "function") result.push(opts);
+	else if (typeof opts === "object") result.push(() => opts);
+	return result;
+};
+
+//#endregion
+//#region src/utils/compose.ts
+const calculateHocsFuncs = (options = {}) => Object.values(options).filter((item) => typeof item === "function").reverse();
+
+//#endregion
+//#region src/utils/statics.ts
+const createStaticsEnhancers = ({ context, options }) => {
+	if (!isEmpty(options)) Object.assign(context, options);
+};
+
+//#endregion
+//#region src/attrs.ts
+const cloneAndEnhance = (defaultOpts, opts) => attrsComponent({
+	...defaultOpts,
+	...opts.name ? { name: opts.name } : void 0,
+	...opts.component ? { component: opts.component } : void 0,
+	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
+	}
+});
+/**
+* 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 = (options) => {
+	const componentName = options.name ?? options.component.displayName ?? options.component.name;
+	const RenderComponent = options.component;
+	const hocsFuncs = [createAttrsHOC(options), ...calculateHocsFuncs(options.compose)];
+	const EnhancedComponent = (props) => {
+		const filteredProps = options.filterAttrs && options.filterAttrs.length > 0 ? omit(props, options.filterAttrs) : props;
+		return RenderComponent(process.env.NODE_ENV !== "production" ? {
+			...filteredProps,
+			"data-attrs": componentName
+		} : filteredProps);
+	};
+	const AttrsComponent = compose(...hocsFuncs)(EnhancedComponent);
+	AttrsComponent.IS_ATTRS = true;
+	AttrsComponent.displayName = componentName;
+	AttrsComponent.meta = {};
+	hoistNonReactStatics(AttrsComponent, options.component);
+	createStaticsEnhancers({
+		context: AttrsComponent.meta,
+		options: options.statics
+	});
+	Object.assign(AttrsComponent, {
+		attrs: (attrs, { priority, filter } = {}) => {
+			const result = {};
+			if (filter) result.filterAttrs = filter;
+			if (priority) {
+				result.priorityAttrs = attrs;
+				return cloneAndEnhance(options, result);
+			}
+			result.attrs = attrs;
+			return cloneAndEnhance(options, result);
+		},
+		config: (opts = {}) => {
+			return cloneAndEnhance(options, pick(opts));
+		},
+		compose: (opts) => cloneAndEnhance(options, { compose: opts }),
+		statics: (opts) => cloneAndEnhance(options, { statics: opts }),
+		getDefaultAttrs: (props) => calculateChainOptions(options.attrs)([props])
+	});
+	return AttrsComponent;
+};
+
+//#endregion
+//#region src/init.ts
+const attrs = ({ name, component }) => {
+	if (process.env.NODE_ENV !== "production") {
+		const 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));
+	}
+	return attrsComponent({
+		name,
+		component,
+		attrs: [],
+		priorityAttrs: [],
+		filterAttrs: [],
+		compose: {},
+		statics: {}
+	});
+};
+
+//#endregion
+//#region src/isAttrsComponent.ts
+/** Runtime type guard — checks if a component was created by `attrs()`. */
+const isAttrsComponent = (component) => {
+	if (component && (typeof component === "object" || typeof component === "function") && component !== null && Object.hasOwn(component, "IS_ATTRS")) return true;
+	return false;
+};
+
+//#endregion
+//#region src/index.ts
+var src_default = attrs;
+
+//#endregion
+export { attrs, src_default as default, isAttrsComponent };
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pyreon/attrs",
+  "version": "0.0.2",
+  "description": "Attrs HOC chaining for Pyreon components",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "source": "./src/index.ts",
+    "import": "./lib/index.js",
+    "types": "./lib/index.d.ts"
+  },
+  "types": "./lib/index.d.ts",
+  "main": "./lib/index.js",
+  "files": [
+    "lib",
+    "!lib/**/*.map",
+    "!lib/analysis",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">= 18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublish": "bun run build",
+    "build": "bun run vl_rolldown_build",
+    "build:watch": "bun run vl_rolldown_build-watch",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@pyreon/core": ">=0.3.0",
+    "@pyreon/ui-core": "^0.0.2"
+  },
+  "devDependencies": {
+    "@vitus-labs/tools-rolldown": "^1.15.0",
+    "@vitus-labs/tools-typescript": "^1.15.0"
+  }
+}