@vitus-labs/attrs 1.2.1 → 1.2.3-alpha.56

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Vit Bokisch
+Copyright (c) 2023-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

package/README.md

@@ -1 +1,176 @@
 # @vitus-labs/attrs
+
+Immutable, chainable default-props factory for React components.
+
+[![npm](https://img.shields.io/npm/v/@vitus-labs/attrs)](https://www.npmjs.com/package/@vitus-labs/attrs)
+[![license](https://img.shields.io/npm/l/@vitus-labs/attrs)](https://github.com/vitus-labs/ui-system/blob/main/LICENSE)
+
+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
+npm install @vitus-labs/attrs
+```
+
+## Quick Start
+
+```tsx
+import attrs from '@vitus-labs/attrs'
+import { Element } from '@vitus-labs/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.
+
+```tsx
+const Component = attrs({
+  name: 'ComponentName',   // required — sets displayName
+  component: BaseComponent, // required — the React component to wrap
+})
+```
+
+### .attrs(props | callback, options?)
+
+Add default props. Can be called multiple times — defaults stack left-to-right.
+
+```tsx
+// 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.
+
+```tsx
+// 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.
+
+```tsx
+const Enhanced = Button.compose({
+  withTheme: (Component) => (props) => (
+    <ThemeProvider><Component {...props} /></ThemeProvider>
+  ),
+  withTracking: trackingHoc,
+})
+
+// Remove a specific HOC from the chain
+const WithoutTracking = Enhanced.compose({ withTracking: null })
+```
+
+### .statics(metadata)
+
+Attach metadata accessible via the `.meta` property.
+
+```tsx
+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.
+
+```tsx
+import { isAttrsComponent } from '@vitus-labs/attrs'
+
+isAttrsComponent(Button) // => true
+isAttrsComponent('div')  // => false
+```
+
+### getDefaultAttrs()
+
+Retrieve the computed default props for a component.
+
+```tsx
+Button.getDefaultAttrs() // => { tag: 'button', alignX: 'center', ... }
+```
+
+## TypeScript
+
+Each `.attrs<P>()` call adds `P` to the component's prop types through `MergeTypes`:
+
+```tsx
+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:
+
+```tsx
+type AllProps = typeof Typed.$$types
+type OriginalProps = typeof Typed.$$originTypes
+type ExtendedProps = typeof Typed.$$extendedTypes
+```
+
+## Peer Dependencies
+
+| Package | Version |
+| ------- | ------- |
+| react | >= 19 |
+| @vitus-labs/core | * |
+
+## License
+
+MIT

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"name":"hooks/useRef.ts","uid":"bf5ad122-1"},{"name":"utils","children":[{"uid":"bf5ad122-3","name":"attrs.ts"},{"uid":"bf5ad122-7","name":"statics.ts"},{"uid":"bf5ad122-9","name":"chaining.ts"},{"uid":"bf5ad122-11","name":"compose.ts"}]},{"name":"hoc/attrsHoc.tsx","uid":"bf5ad122-5"},{"uid":"bf5ad122-13","name":"attrs.tsx"},{"uid":"bf5ad122-15","name":"init.ts"},{"uid":"bf5ad122-17","name":"isAttrsComponent.tsx"},{"uid":"bf5ad122-19","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"bf5ad122-1":{"renderedLength":235,"gzipLength":144,"brotliLength":0,"metaUid":"bf5ad122-0"},"bf5ad122-3":{"renderedLength":488,"gzipLength":275,"brotliLength":0,"metaUid":"bf5ad122-2"},"bf5ad122-5":{"renderedLength":1229,"gzipLength":443,"brotliLength":0,"metaUid":"bf5ad122-4"},"bf5ad122-7":{"renderedLength":138,"gzipLength":124,"brotliLength":0,"metaUid":"bf5ad122-6"},"bf5ad122-9":{"renderedLength":244,"gzipLength":158,"brotliLength":0,"metaUid":"bf5ad122-8"},"bf5ad122-11":{"renderedLength":133,"gzipLength":125,"brotliLength":0,"metaUid":"bf5ad122-10"},"bf5ad122-13":{"renderedLength":4929,"gzipLength":1391,"brotliLength":0,"metaUid":"bf5ad122-12"},"bf5ad122-15":{"renderedLength":856,"gzipLength":364,"brotliLength":0,"metaUid":"bf5ad122-14"},"bf5ad122-17":{"renderedLength":252,"gzipLength":172,"brotliLength":0,"metaUid":"bf5ad122-16"},"bf5ad122-19":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"bf5ad122-18"}},"nodeMetas":{"bf5ad122-0":{"id":"/src/hooks/useRef.ts","moduleParts":{"index.js":"bf5ad122-1"},"imported":[{"uid":"bf5ad122-21"}],"importedBy":[{"uid":"bf5ad122-23"}]},"bf5ad122-2":{"id":"/src/utils/attrs.ts","moduleParts":{"index.js":"bf5ad122-3"},"imported":[{"uid":"bf5ad122-20"}],"importedBy":[{"uid":"bf5ad122-12"},{"uid":"bf5ad122-4"}]},"bf5ad122-4":{"id":"/src/hoc/attrsHoc.tsx","moduleParts":{"index.js":"bf5ad122-5"},"imported":[{"uid":"bf5ad122-21"},{"uid":"bf5ad122-2"}],"importedBy":[{"uid":"bf5ad122-24"}]},"bf5ad122-6":{"id":"/src/utils/statics.ts","moduleParts":{"index.js":"bf5ad122-7"},"imported":[{"uid":"bf5ad122-20"}],"importedBy":[{"uid":"bf5ad122-12"}]},"bf5ad122-8":{"id":"/src/utils/chaining.ts","moduleParts":{"index.js":"bf5ad122-9"},"imported":[],"importedBy":[{"uid":"bf5ad122-12"}]},"bf5ad122-10":{"id":"/src/utils/compose.ts","moduleParts":{"index.js":"bf5ad122-11"},"imported":[],"importedBy":[{"uid":"bf5ad122-12"}]},"bf5ad122-12":{"id":"/src/attrs.tsx","moduleParts":{"index.js":"bf5ad122-13"},"imported":[{"uid":"bf5ad122-21"},{"uid":"bf5ad122-22"},{"uid":"bf5ad122-20"},{"uid":"bf5ad122-23"},{"uid":"bf5ad122-24"},{"uid":"bf5ad122-6"},{"uid":"bf5ad122-8"},{"uid":"bf5ad122-10"},{"uid":"bf5ad122-2"}],"importedBy":[{"uid":"bf5ad122-14"}]},"bf5ad122-14":{"id":"/src/init.ts","moduleParts":{"index.js":"bf5ad122-15"},"imported":[{"uid":"bf5ad122-20"},{"uid":"bf5ad122-12"}],"importedBy":[{"uid":"bf5ad122-18"}]},"bf5ad122-16":{"id":"/src/isAttrsComponent.tsx","moduleParts":{"index.js":"bf5ad122-17"},"imported":[],"importedBy":[{"uid":"bf5ad122-18"}]},"bf5ad122-18":{"id":"/src/index.ts","moduleParts":{"index.js":"bf5ad122-19"},"imported":[{"uid":"bf5ad122-14"},{"uid":"bf5ad122-16"}],"importedBy":[],"isEntry":true},"bf5ad122-20":{"id":"@vitus-labs/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"bf5ad122-14"},{"uid":"bf5ad122-12"},{"uid":"bf5ad122-6"},{"uid":"bf5ad122-2"}],"isExternal":true},"bf5ad122-21":{"id":"react","moduleParts":{},"imported":[],"importedBy":[{"uid":"bf5ad122-12"},{"uid":"bf5ad122-0"},{"uid":"bf5ad122-4"}],"isExternal":true},"bf5ad122-22":{"id":"hoist-non-react-statics","moduleParts":{},"imported":[],"importedBy":[{"uid":"bf5ad122-12"}],"isExternal":true},"bf5ad122-23":{"id":"/src/hooks/index.ts","moduleParts":{},"imported":[{"uid":"bf5ad122-0"}],"importedBy":[{"uid":"bf5ad122-12"}]},"bf5ad122-24":{"id":"/src/hoc/index.ts","moduleParts":{},"imported":[{"uid":"bf5ad122-4"}],"importedBy":[{"uid":"bf5ad122-12"}]}},"env":{"rollup":"4.35.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"name":"utils","children":[{"uid":"4bb57168-1","name":"attrs.ts"},{"uid":"4bb57168-11","name":"chaining.ts"},{"uid":"4bb57168-13","name":"compose.ts"},{"uid":"4bb57168-15","name":"statics.ts"}]},{"name":"hoc","children":[{"uid":"4bb57168-3","name":"attrsHoc.tsx"},{"uid":"4bb57168-5","name":"index.ts"}]},{"name":"hooks","children":[{"uid":"4bb57168-7","name":"useRef.ts"},{"uid":"4bb57168-9","name":"index.ts"}]},{"uid":"4bb57168-17","name":"attrs.tsx"},{"uid":"4bb57168-19","name":"init.ts"},{"uid":"4bb57168-21","name":"isAttrsComponent.tsx"},{"uid":"4bb57168-23","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"4bb57168-1":{"renderedLength":440,"gzipLength":269,"brotliLength":0,"metaUid":"4bb57168-0"},"4bb57168-3":{"renderedLength":1263,"gzipLength":594,"brotliLength":0,"metaUid":"4bb57168-2"},"4bb57168-5":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"4bb57168-4"},"4bb57168-7":{"renderedLength":702,"gzipLength":384,"brotliLength":0,"metaUid":"4bb57168-6"},"4bb57168-9":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"4bb57168-8"},"4bb57168-11":{"renderedLength":262,"gzipLength":182,"brotliLength":0,"metaUid":"4bb57168-10"},"4bb57168-13":{"renderedLength":168,"gzipLength":152,"brotliLength":0,"metaUid":"4bb57168-12"},"4bb57168-15":{"renderedLength":163,"gzipLength":144,"brotliLength":0,"metaUid":"4bb57168-14"},"4bb57168-17":{"renderedLength":3086,"gzipLength":1186,"brotliLength":0,"metaUid":"4bb57168-16"},"4bb57168-19":{"renderedLength":496,"gzipLength":291,"brotliLength":0,"metaUid":"4bb57168-18"},"4bb57168-21":{"renderedLength":310,"gzipLength":230,"brotliLength":0,"metaUid":"4bb57168-20"},"4bb57168-23":{"renderedLength":61,"gzipLength":75,"brotliLength":0,"metaUid":"4bb57168-22"}},"nodeMetas":{"4bb57168-0":{"id":"/src/utils/attrs.ts","moduleParts":{"index.js":"4bb57168-1"},"imported":[{"uid":"4bb57168-24"}],"importedBy":[{"uid":"4bb57168-16"},{"uid":"4bb57168-2"}]},"4bb57168-2":{"id":"/src/hoc/attrsHoc.tsx","moduleParts":{"index.js":"4bb57168-3"},"imported":[{"uid":"4bb57168-25"},{"uid":"4bb57168-0"},{"uid":"4bb57168-26"}],"importedBy":[{"uid":"4bb57168-4"}]},"4bb57168-4":{"id":"/src/hoc/index.ts","moduleParts":{"index.js":"4bb57168-5"},"imported":[{"uid":"4bb57168-2"}],"importedBy":[{"uid":"4bb57168-16"}]},"4bb57168-6":{"id":"/src/hooks/useRef.ts","moduleParts":{"index.js":"4bb57168-7"},"imported":[{"uid":"4bb57168-25"}],"importedBy":[{"uid":"4bb57168-8"}]},"4bb57168-8":{"id":"/src/hooks/index.ts","moduleParts":{"index.js":"4bb57168-9"},"imported":[{"uid":"4bb57168-6"}],"importedBy":[{"uid":"4bb57168-16"}]},"4bb57168-10":{"id":"/src/utils/chaining.ts","moduleParts":{"index.js":"4bb57168-11"},"imported":[],"importedBy":[{"uid":"4bb57168-16"}]},"4bb57168-12":{"id":"/src/utils/compose.ts","moduleParts":{"index.js":"4bb57168-13"},"imported":[],"importedBy":[{"uid":"4bb57168-16"}]},"4bb57168-14":{"id":"/src/utils/statics.ts","moduleParts":{"index.js":"4bb57168-15"},"imported":[{"uid":"4bb57168-24"}],"importedBy":[{"uid":"4bb57168-16"}]},"4bb57168-16":{"id":"/src/attrs.tsx","moduleParts":{"index.js":"4bb57168-17"},"imported":[{"uid":"4bb57168-24"},{"uid":"4bb57168-25"},{"uid":"4bb57168-4"},{"uid":"4bb57168-8"},{"uid":"4bb57168-0"},{"uid":"4bb57168-10"},{"uid":"4bb57168-12"},{"uid":"4bb57168-14"},{"uid":"4bb57168-26"}],"importedBy":[{"uid":"4bb57168-18"}]},"4bb57168-18":{"id":"/src/init.ts","moduleParts":{"index.js":"4bb57168-19"},"imported":[{"uid":"4bb57168-24"},{"uid":"4bb57168-16"}],"importedBy":[{"uid":"4bb57168-22"}]},"4bb57168-20":{"id":"/src/isAttrsComponent.tsx","moduleParts":{"index.js":"4bb57168-21"},"imported":[],"importedBy":[{"uid":"4bb57168-22"}]},"4bb57168-22":{"id":"/src/index.ts","moduleParts":{"index.js":"4bb57168-23"},"imported":[{"uid":"4bb57168-18"},{"uid":"4bb57168-20"}],"importedBy":[],"isEntry":true},"4bb57168-24":{"id":"@vitus-labs/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"4bb57168-18"},{"uid":"4bb57168-16"},{"uid":"4bb57168-0"},{"uid":"4bb57168-14"}]},"4bb57168-25":{"id":"react","moduleParts":{},"imported":[],"importedBy":[{"uid":"4bb57168-16"},{"uid":"4bb57168-2"},{"uid":"4bb57168-6"}]},"4bb57168-26":{"id":"react/jsx-runtime","moduleParts":{},"imported":[],"importedBy":[{"uid":"4bb57168-16"},{"uid":"4bb57168-2"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;