praxis-kit 1.1.0 → 1.1.1

package/README.md

@@ -0,0 +1,196 @@
+# Praxis Kit
+
+**Build components that enforce their own structure.**
+
+Praxis Kit is a framework-neutral component infrastructure framework that validates component
+composition, accessibility rules, and rendering contracts at runtime. Instead of allowing invalid UI
+structures to render and fail later, Praxis catches them immediately.
+
+```tsx
+<Tabs>
+  <TabsTrigger />
+</Tabs>
+```
+
+```text
+✖ TabsList required
+✖ TabsPanel required
+```
+
+```tsx
+<Tabs>
+  <TabsList>
+    <TabsTrigger />
+  </TabsList>
+  <TabsPanel>Content</TabsPanel>
+</Tabs>
+```
+
+```text
+✔ Valid structure
+```
+
+---
+
+## Installation
+
+All adapters and tooling are bundled in the single `praxis-kit` package:
+
+```bash
+npm install praxis-kit
+```
+
+Then import from the sub-entry for your framework:
+
+```ts
+import { createContractComponent } from 'praxis-kit/react' // React 19+
+import { createContractComponent } from 'praxis-kit/vue'
+import { createContractComponent } from 'praxis-kit/svelte'
+import { createContractComponent } from 'praxis-kit/solid'
+import { createContractComponent } from 'praxis-kit/preact'
+```
+
+Optional tooling sub-entries:
+
+```ts
+import plugin from 'praxis-kit/eslint' // ESLint rules
+import plugin from 'praxis-kit/vite-plugin' // Vite static analysis
+import plugin from 'praxis-kit/tailwind' // Tailwind class pipeline
+```
+
+> **Migrating from `@praxis-kit/*`?** Run `pnpm dlx @praxis-kit/codemod migrate` to rewrite import
+> paths and the factory rename automatically.
+
+---
+
+## Why Praxis?
+
+Traditional component libraries validate props, types, and accessibility attributes. Praxis
+additionally validates:
+
+- required children and parent/child relationships
+- component composition contracts
+- accessibility policies
+- rendering capabilities
+
+…before broken UI reaches production.
+
+---
+
+## What Problems Does It Solve?
+
+### Structural Validation
+
+```tsx
+<Dialog>
+  <DialogContent />
+</Dialog>
+```
+
+```text
+✖ DialogTrigger missing
+```
+
+### Accessibility Enforcement
+
+```tsx
+<nav role="navigation" />
+```
+
+```text
+✖ Redundant role — stripped before it reaches the DOM
+```
+
+### Polymorphic Rendering
+
+```tsx
+<Button as="a" href="/pricing">
+  Pricing
+</Button>
+```
+
+```html
+<a href="/pricing">Pricing</a>
+```
+
+### Framework-Neutral Core
+
+Business logic lives outside framework adapters. One engine, five runtimes.
+
+```text
+praxis-kit
+  ├─ praxis-kit/react
+  ├─ praxis-kit/svelte
+  ├─ praxis-kit/vue
+  ├─ praxis-kit/solid
+  ├─ praxis-kit/preact
+  ├─ praxis-kit/lit
+  └─ praxis-kit/web
+```
+
+---
+
+## Packages
+
+| Sub-entry                | Description                                                       |
+| ------------------------ | ----------------------------------------------------------------- |
+| `praxis-kit/react`       | React 19+ · `praxis-kit/react/legacy` for React 18                |
+| `praxis-kit/vue`         | Vue 3                                                             |
+| `praxis-kit/solid`       | Solid · client and SSR                                            |
+| `praxis-kit/preact`      | Preact                                                            |
+| `praxis-kit/svelte`      | Svelte 5                                                          |
+| `praxis-kit/lit`         | Lit                                                               |
+| `praxis-kit/web`         | Vanilla Custom Elements — no framework required                   |
+| `praxis-kit/tailwind`    | Layout-aware Tailwind class pipeline plugin                       |
+| `praxis-kit/vite-plugin` | Vite plugins for static composition, SSR, and contract validation |
+| `praxis-kit/eslint`      | ESLint rules for enforcing Praxis Kit patterns                    |
+| `praxis-kit/ts-plugin`   | TypeScript language service plugin with inline diagnostics        |
+| `praxis-kit/codemod`     | Codemods for migrations                                           |
+| `praxis-kit/playwright`  | Playwright CT helpers — ARIA snapshots, axe sweeps, keyboard      |
+
+---
+
+## vs. Other Tools
+
+|                | Headless Components | Structural Contracts | Runtime Composition Validation | Accessibility Policies | Framework-Neutral Core |
+| -------------- | ------------------- | -------------------- | ------------------------------ | ---------------------- | ---------------------- |
+| **Praxis Kit** | — rules only        | ✓                    | ✓                              | ✓                      | ✓                      |
+| **Radix UI**   | ✓                   | ✗                    | ✗                              | Partial                | ✗ — React only         |
+| **Ark UI**     | ✓                   | Partial              | ✗                              | Partial                | Partial                |
+| **React Aria** | ✓                   | ✗                    | ✗                              | ✓                      | ✗                      |
+| **CVA**        | ✗                   | ✗                    | ✗                              | ✗                      | ✗ — class strings only |
+
+---
+
+## Philosophy
+
+TypeScript can tell you that a prop exists. Praxis can tell you that a component hierarchy is valid.
+
+```tsx
+<Tabs>
+  <p>Hello</p>
+</Tabs>
+```
+
+TypeScript: `✔ Compiles` — Praxis: `✖ Invalid Tabs structure`
+
+---
+
+## Learn Praxis in 10 Minutes
+
+The [Getting Started guide](GETTING_STARTED.md) walks from a minimal component:
+
+```ts
+const Box = createContractComponent({ tag: 'div' })
+```
+
+to variants, compound variants, polymorphic rendering, accessibility validation, structural
+contracts, slot rendering, and presets.
+
+**[→ Start here](GETTING_STARTED.md)**
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/preact/index.d.ts

@@ -289,4 +289,4 @@ type SlottableProps = {
 };
 declare function Slottable({ children }: SlottableProps): AnyVNode;
 
-export { type ElementRef, type PolymorphicComponent, type PolymorphicProps, type PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent, defineContractComponent, disabledProps, invalidProps };
+export { type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent, defineContractComponent, disabledProps, invalidProps };

package/dist/react/index.d.ts

@@ -24,4 +24,4 @@ declare namespace Slot {
     var displayName: string;
 }
 
-export { PolymorphicComponent, ReactFactoryOptions, Slot, createAriaEnforcedComponent, createChildrenEnforcedComponent, createContractComponent, createContractedComponent, createPolymorphicComponent, defineContractComponent };
+export { ElementType, EmptyRecord, PolymorphicComponent, PolymorphicGenerics, ReactFactoryOptions, Slot, createAriaEnforcedComponent, createChildrenEnforcedComponent, createContractComponent, createContractedComponent, createPolymorphicComponent, defineContractComponent };

package/dist/react/legacy.d.ts

@@ -18,4 +18,4 @@ type SlotProps = {
 };
 declare const Slot: react.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & react.RefAttributes<unknown>>;
 
-export { PolymorphicComponent, ReactFactoryOptions, Slot, createAriaEnforcedComponent, createChildrenEnforcedComponent, createContractComponent, createContractedComponent, createPolymorphicComponent };
+export { ElementType, EmptyRecord, PolymorphicComponent, PolymorphicGenerics, ReactFactoryOptions, Slot, createAriaEnforcedComponent, createChildrenEnforcedComponent, createContractComponent, createContractedComponent, createPolymorphicComponent };

package/dist/solid/index.d.ts

@@ -284,4 +284,4 @@ declare function createContractComponent<TDefault extends ElementType, Props ext
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
-export { type ElementRef, type PolymorphicComponent, type PolymorphicProps, type SolidFactoryOptions, createContractComponent, defineContractComponent, disabledProps, invalidProps };
+export { type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type SolidFactoryOptions, createContractComponent, defineContractComponent, disabledProps, invalidProps };

package/dist/svelte/index.d.ts

@@ -340,4 +340,4 @@ declare function createContractComponent<TDefault extends ElementType, Props ext
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
-export { type BuiltRuntime, type FilterPredicate, type SvelteFactoryOptions, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent, disabledProps, invalidProps };
+export { type BuiltRuntime, type ElementType, type EmptyRecord, type FilterPredicate, type PolymorphicGenerics, type SvelteFactoryOptions, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent, disabledProps, invalidProps };

package/dist/vue/index.d.ts

@@ -306,4 +306,4 @@ declare function createContractComponent<TDefault extends ElementType, Props ext
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
-export { type PolymorphicComponent, type PolymorphicProps, type PolymorphicWithAsChild, Slottable, type SlottableProps, type VueFactoryOptions, createContractComponent, defineContractComponent, disabledProps, invalidProps };
+export { type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, Slottable, type SlottableProps, type VueFactoryOptions, createContractComponent, defineContractComponent, disabledProps, invalidProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-kit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "type": "module",
   "exports": {
     "./react": {
@@ -137,7 +137,7 @@
     "url": "git+https://github.com/slowebworkz/praxis-kit.git",
     "directory": "packages/kit"
   },
-  "homepage": "https://github.com/slowebworkz/praxis-kit/tree/main/packages/kit#readme",
+  "homepage": "https://github.com/slowebworkz/praxis-kit#readme",
   "bugs": {
     "url": "https://github.com/slowebworkz/praxis-kit/issues"
   },