praxis-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K Huehn
+
+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,77 @@
+# praxis-kit (packages/kit)
+
+The **single published package**. Everything users install comes from here; every other workspace in
+the repo is private and gets bundled into this package's entry points at build time.
+
+```bash
+pnpm add praxis-kit
+```
+
+## Status
+
+Built (`tsdown`). The public `exports` surface, the framework-neutral entry files (`contract.ts` /
+`guards.ts` / `html.ts` / `utils.ts` — thin re-exports of `@praxis-kit/core`, `primitive`, and
+`diagnostics`), and Changesets (this is the only package it versions) are all in place. All 7
+framework adapters are ready, including Solid and Svelte's declaration file — both formerly deferred
+gaps, now resolved (see below). **Not yet published** (`private: true`) — pending review of the
+build itself and the release-process wiring (CI release job, `private: false` flip, first tag), not
+on any remaining source gap.
+
+| Entry                                     | Bundles                    | State                                                                                                                     |
+| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `praxis-kit/react` (+ `/react/legacy`)    | `adapters/react`           | ✅ ready                                                                                                                  |
+| `praxis-kit/preact`                       | `adapters/preact`          | ✅ ready                                                                                                                  |
+| `praxis-kit/vue`                          | `adapters/vue`             | ✅ ready                                                                                                                  |
+| `praxis-kit/solid`                        | `adapters/solid`           | ✅ ready — real Solid JSX transform via `unplugin-solid/rolldown`                                                         |
+| `praxis-kit/svelte`                       | `adapters/svelte`          | ✅ ready — declarations generate correctly as of `rolldown-plugin-dts@^0.28.5` (via tsdown 0.23.0)                        |
+| `praxis-kit/lit`                          | `adapters/lit`             | ✅ ready                                                                                                                  |
+| `praxis-kit/web`                          | `adapters/web`             | ✅ ready                                                                                                                  |
+| `praxis-kit/tailwind` (+ `.css`)          | `lib/tailwind`             | ✅ ready                                                                                                                  |
+| `praxis-kit/eslint`                       | `plugins/eslint`           | ✅ ready                                                                                                                  |
+| `praxis-kit/ts-plugin`                    | `plugins/typescript` (CJS) | ✅ ready                                                                                                                  |
+| `praxis-kit/vite-plugin`                  | `plugins/vite`             | ✅ ready — requires the consumer's own `typescript` at runtime (real `import ts from 'typescript'`, not a build artifact) |
+| `praxis-kit/codemod`                      | `tooling/codemod`          | ✅ ready — fully self-contained; `ts-morph` vendors its own TypeScript, no peer needed                                    |
+| `praxis-kit/{contract,guards,html,utils}` | this folder                | ✅ ready                                                                                                                  |
+
+## Formerly-deferred gaps, now resolved
+
+- **Solid.** No rolldown-native Solid JSX transform was known to exist in this workspace when this
+  build was first written. `unplugin-solid/rolldown` (backed by `babel-preset-solid`, the same
+  compiler `esbuild-plugin-solid` wraps for `../pk`'s tsup build) fills that gap — confirmed via
+  tsdown's own documented Solid recipe.
+- **Svelte's type declarations.** `svelte`'s own shipped types use an ambient
+  `declare module 'svelte' { ... }` augmentation rather than plain top-level `export`s, which
+  `rolldown-plugin-dts@0.27.x` couldn't bundle through. Fixed upstream in
+  `rolldown-plugin-dts@^0.28.5` ("treat script-style ambient declarations as modules"), pulled in
+  via a `tsdown` bump to `0.23.0`.
+
+## Build
+
+`tsdown.config.ts` (this folder) — one entry per published subpath, plus a shared
+`_shared/diagnostics` chunk. Two invariants `scripts/postbuild.ts` enforces after the build:
+
+1. **No unpublished names in output.** JS bundles internal `@praxis-kit/*` packages directly
+   (`deps.neverBundle` opts out only each entry's framework peer and `@praxis-kit/diagnostics`);
+   declarations resolve `@praxis-kit/*` sources via `dts.compilerOptions.paths`. `publint` checks
+   the packed result (`pnpm lint:pkg`).
+2. **Single `Diagnostics` identity.** `@praxis-kit/diagnostics` is built once into
+   `dist/_shared/diagnostics.*` and every other entry's external `@praxis-kit/diagnostics` specifier
+   is rewritten to a relative import into it — a class with private members bundled per entry would
+   be a different type and a different runtime class in each.
+
+Framework packages (`react`, `vue`, `preact`, `solid-js`, `lit`, `svelte`) stay optional peer
+dependencies. `typescript` is an optional peer too, for `vite-plugin` specifically — `codemod` needs
+none (see above), and no other entry touches it.
+
+## Verifying a release candidate
+
+`publint` and a workspace typecheck check `dist/` shape and source types — neither installs the
+published package the way a real consumer would. `pnpm --filter praxis-kit test:pack` does: builds
+fresh, packs, installs the tarball plus every framework peer into an isolated fixture (outside this
+repo's own pnpm workspace, so nothing resolves via hoisting), imports every plain-JS public entry,
+resolves types for every typed entry, and runs `praxis-codemod` through its real `.bin` symlink —
+the exact sequence that caught two real bugs no amount of `publint`/typecheck/lint surfaced (see
+`DECISIONS.md`). Wired into `prepublishOnly`, so a real `npm publish` can't skip it.
+
+See `DECISIONS.md` ("`packages/kit` — real build (tsup → tsdown)") for the full writeup, including
+why this isn't a straight port of `../pk`'s `tsup` config.

package/dist/_shared/diagnostics.d.ts

@@ -0,0 +1,312 @@
+import "clsx";
+//#region ../../lib/diagnostics/src/category.d.ts
+/** The kind of rule a diagnostic reports. The load-bearing distinction:
+ *
+ *  - `HTML` / `ARIA` — **spec compliance**. The markup or ARIA usage is invalid
+ *    per the HTML standard or the ARIA spec. A fact, not a judgement.
+ *  - `Accessibility` — **best-practice guidance**. The usage is spec-valid but
+ *    inadvisable (e.g. a placeholder standing in for a label). Advisory.
+ *
+ *  Keep that split deliberate: a rule belongs in `Accessibility` only when it is
+ *  *not* an `HTML`/`ARIA` validity fact. The code ranges mirror it — `ARIA2xxx`
+ *  and `HTML3xxx` are validity, `A11Y8xxx` is guidance (see `codes.ts`). */
+export declare enum DiagnosticCategory {
+  Contract = 0,
+  HTML = 1,
+  ARIA = 2,
+  Composition = 3,
+  Rendering = 4,
+  Accessibility = 5,
+  Performance = 6,
+  Internal = 7,
+  Deprecation = 8,
+  Lint = 9
+}
+//#endregion
+//#region ../../lib/diagnostics/src/codes.d.ts
+export declare enum DiagnosticCode {
+  MissingRequiredChild = "COMP1001",
+  InvalidParent = "COMP1002",
+  InvalidChild = "COMP1003",
+  UnexpectedChild = "COMP1004",
+  AmbiguousChild = "COMP1005",
+  CardinalityMin = "COMP1006",
+  CardinalityMax = "COMP1007",
+  PositionViolation = "COMP1008",
+  AllowedAsViolation = "COMP1009",
+  SlotExclusive = "SLOT1001",
+  SlotSingleChild = "SLOT1002",
+  SlotDiscardedChildren = "SLOT1003",
+  SlotRenderFn = "SLOT1004",
+  MissingAriaRelationship = "ARIA2001",
+  AriaViolation = "ARIA2002",
+  AriaAttributeInvalid = "ARIA2003",
+  AriaMissingLiveRegion = "ARIA2004",
+  AriaMissingAtomic = "ARIA2005",
+  AriaRelevantInvalidToken = "ARIA2006",
+  AriaRelevantSuperseded = "ARIA2007",
+  AriaInvalidRole = "ARIA2008",
+  AriaMissingAccessibleName = "ARIA2009",
+  AriaAttributeOnPresentational = "ARIA2010",
+  AriaHiddenOnFocusable = "ARIA2011",
+  AriaRequiredProperty = "ARIA2012",
+  AriaInvalidAttributeValue = "ARIA2013",
+  AriaRedundantLevelAttribute = "ARIA2014",
+  AriaNameProhibited = "ARIA2015",
+  InvalidHeadingHierarchy = "HTML3001",
+  HtmlEmptyRole = "HTML3002",
+  HtmlImplicitRoleRedundant = "HTML3003",
+  HtmlImplicitRoleOverride = "HTML3004",
+  HtmlStandaloneRegionOverride = "HTML3005",
+  HtmlLandmarkRoleOverride = "HTML3006",
+  HtmlInvalidChild = "HTML3007",
+  HtmlRoleNotPermitted = "HTML3008",
+  HtmlInputUnsupportedType = "HTML3101",
+  HtmlInputCheckedIgnoredForType = "HTML3102",
+  HtmlInputMultipleIgnoredForType = "HTML3103",
+  HtmlInputMaxLengthIgnoredForType = "HTML3104",
+  HtmlInputMinLengthIgnoredForType = "HTML3105",
+  HtmlInputPatternIgnoredForType = "HTML3106",
+  HtmlInputMinIgnoredForType = "HTML3107",
+  HtmlInputMaxIgnoredForType = "HTML3108",
+  HtmlInputStepIgnoredForType = "HTML3109",
+  HtmlInputAcceptIgnoredForType = "HTML3110",
+  HtmlInputCaptureIgnoredForType = "HTML3111",
+  HtmlInputSizeIgnoredForType = "HTML3112",
+  HtmlInputAltIgnoredForType = "HTML3113",
+  HtmlInputHeightIgnoredForType = "HTML3114",
+  HtmlInputWidthIgnoredForType = "HTML3115",
+  HtmlAnchorDangerousHref = "HTML3201",
+  A11yInputMissingAccessibleName = "A11Y8100",
+  A11yInputPlaceholderNotLabel = "A11Y8101",
+  A11yInputPasswordAutocomplete = "A11Y8102",
+  A11yInputRequiredReadOnlyConflict = "A11Y8103",
+  A11yAnchorRoleButtonWithHref = "A11Y8200",
+  A11yAnchorAriaDisabledInert = "A11Y8201",
+  InvalidRenderingTarget = "RENDER4001",
+  LintDeadCompoundKey = "LINT5001",
+  LintDeadCompoundValue = "LINT5002",
+  LintDeadCompoundNonLiteral = "LINT5003",
+  LintMissingStrict = "LINT5004",
+  LintInvalidDefaultKey = "LINT5005",
+  LintInvalidDefaultValue = "LINT5006",
+  LintInvalidDefaultNonLiteral = "LINT5007",
+  LintNegativeMin = "LINT5008",
+  LintNegativeMax = "LINT5009",
+  LintMaxLessThanMin = "LINT5010",
+  LintZeroMax = "LINT5011",
+  LintMultipleFirst = "LINT5012",
+  LintMultipleLast = "LINT5013",
+  LintMinSumExceedsCapacity = "LINT5014",
+  LintCardinalityViolation = "LINT5015",
+  LintAriaTagOverride = "LINT5016",
+  ContractUnknownVariantDim = "COMP1010",
+  ContractUnknownVariantValue = "COMP1011",
+  ContractUnknownRecipeKey = "COMP1012",
+  ContractInvalidVariantValue = "COMP1013",
+  TailwindMultipleDisplayProps = "CSS6001",
+  TailwindReservedLayoutLiteral = "CSS6002",
+  TailwindDeadVariantClass = "CSS6003",
+  TailwindLayoutOnVoidTag = "CSS6004",
+  PluginInvalidShape = "PLUGIN7001",
+  PluginPipelineReturnType = "PLUGIN7002",
+  InternalError = "INTERNAL9000"
+}
+//#endregion
+//#region ../../lib/diagnostics/src/severity.d.ts
+export declare enum Severity {
+  Debug = 0,
+  Info = 1,
+  Warning = 2,
+  Error = 3,
+  Fatal = 4
+}
+export declare function isAtLeast(s: Severity, threshold: Severity): boolean;
+//#endregion
+//#region ../../lib/foundation/src/string-map.d.ts
+/**
+ * A string-keyed object whose values are of type `T`.
+ */
+type StringMap<T = unknown> = Record<string, T>;
+/**
+ * A string-keyed object with values of unknown type.
+ */
+type AnyRecord = StringMap<unknown>;
+//#endregion
+//#region ../../lib/diagnostics/src/types/diagnostic.d.ts
+/** Data a *reader* needs to understand this diagnostic — the values a formatter
+ *  would interpolate into `rationale`/`message` (the offending prop name, the
+ *  expected vs actual child, the ARIA token). Human-oriented. */
+type Context = AnyRecord;
+/** Data a *consumer* (build plugin, editor integration, telemetry) keys off —
+ *  never rendered to a person. Machine-oriented. Keep the split with `Context`
+ *  deliberate: without it, both degrade into interchangeable dumping grounds. */
+type Metadata = AnyRecord;
+interface SourcePosition {
+  line: number;
+  col: number;
+}
+interface SourceLocation {
+  file: string;
+  start: SourcePosition;
+  end?: SourcePosition;
+}
+interface DiagnosticSuggestion {
+  title: string;
+  description?: string;
+  fix?: string;
+}
+interface Diagnostic {
+  code: DiagnosticCode;
+  severity: Severity;
+  category: DiagnosticCategory;
+  message: string;
+  rationale?: string;
+  component?: string;
+  contract?: string;
+  location?: SourceLocation;
+  suggestions?: DiagnosticSuggestion[];
+  /** Values a formatter interpolates into the message — human-oriented. */
+  context?: Context;
+  /** Structured data for tooling — never rendered. Machine-oriented. */
+  metadata?: Metadata;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/types/reporter.d.ts
+/** Sink for diagnostics the policy decided to surface. Implementations decide
+ *  what "report" means — collect, print, throw, forward. Injected into
+ *  `Diagnostics`; nothing in this package picks one for you. */
+interface DiagnosticReporter {
+  report(diagnostic: Diagnostic): void;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/policy.d.ts
+export declare enum Enforcement {
+  Ignore = 0,
+  Report = 1,
+  Throw = 2
+}
+interface DiagnosticPolicy {
+  resolve(diagnostic: Diagnostic): Enforcement;
+}
+interface DefaultPolicyOptions {
+  /** Severities `>=` this are reported. Default `Severity.Info`. */
+  reportThreshold?: Severity;
+  /** Severities `>=` this throw instead. Default `Severity.Fatal`. Must be
+   *  `>= reportThreshold` — a throw threshold below the report threshold makes
+   *  the report band empty and is always a misconfiguration. */
+  throwThreshold?: Severity;
+}
+export declare class DefaultPolicy implements DiagnosticPolicy {
+  private readonly reportThreshold;
+  private readonly throwThreshold;
+  constructor({ reportThreshold, throwThreshold }?: DefaultPolicyOptions);
+  resolve(diagnostic: Diagnostic): Enforcement;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/diagnostics.d.ts
+/** The write-side shape: everything on `Diagnostic` except `severity`, which the
+ *  `debug`/`info`/`warn`/`error`/`fatal` helpers stamp. */
+type DiagnosticInput = Omit<Diagnostic, 'severity'>;
+export declare class Diagnostics {
+  private readonly reporter;
+  private readonly policy;
+  /** Cheap gate for callers: `false` means a `Severity.Warning` diagnostic would
+   *  be ignored by the policy, so warning-level validation work (often the
+   *  expensive kind) can be skipped entirely. Precomputed at construction.
+   *
+   *  Scoped to Warning deliberately — it is **not** a general "diagnostics on"
+   *  flag. A policy that ignores Warning but reports Info or throws on Error
+   *  still reads `false` here; check the policy directly for other severities. */
+  readonly warnActive: boolean;
+  constructor(reporter: DiagnosticReporter, policy?: DiagnosticPolicy);
+  report(diagnostic: Diagnostic): Diagnostic;
+  debug(input: DiagnosticInput): Diagnostic;
+  info(input: DiagnosticInput): Diagnostic;
+  warn(input: DiagnosticInput): Diagnostic;
+  error(input: DiagnosticInput): Diagnostic;
+  fatal(input: DiagnosticInput): Diagnostic;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/error.d.ts
+export declare class PraxisError extends Error {
+  readonly diagnostic: Diagnostic;
+  constructor(diagnostic: Diagnostic);
+}
+//#endregion
+//#region ../../lib/diagnostics/src/formatter.d.ts
+type Formatter = (diagnostic: Diagnostic) => string;
+export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+//#endregion
+//#region ../../lib/diagnostics/src/result.d.ts
+interface ValidationResult {
+  valid: boolean;
+  diagnostics: readonly Diagnostic[];
+}
+type Ok<T> = {
+  readonly ok: true;
+  readonly value: T;
+};
+type Err<E> = {
+  readonly ok: false;
+  readonly error: E;
+};
+type Result<T, E = ValidationResult> = Ok<T> | Err<E>;
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E>(error: E): Err<E>;
+//#endregion
+//#region ../../lib/diagnostics/src/async-console-reporter.d.ts
+/** A console reporter that batches a microtask's worth of diagnostics into one
+ *  flush and drops duplicates within that window.
+ *
+ *  Dedup key is the **formatted string**, on purpose: this reporter's job is
+ *  console UX — don't print the same line twice. Two distinct diagnostics that
+ *  format identically (same code + message, different file/location) collapse to
+ *  one printed line. If you need every distinct diagnostic preserved, use
+ *  `CollectingReporter`; this one is not a lossless channel. (A
+ *  location-aware key is a possible future refinement if `formatDiagnostic`
+ *  stops including enough identity.) */
+export declare class AsyncConsoleReporter implements DiagnosticReporter {
+  private readonly pending;
+  private scheduled;
+  report(diagnostic: Diagnostic): void;
+  /** Clears pending messages. Exposed for test isolation only. */
+  reset(): void;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/collecting-reporter.d.ts
+export declare class CollectingReporter implements DiagnosticReporter {
+  private readonly collected;
+  report(diagnostic: Diagnostic): void;
+  get diagnostics(): readonly Diagnostic[];
+  clear(): void;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/console-reporter.d.ts
+export declare class ConsoleReporter implements DiagnosticReporter {
+  report(diagnostic: Diagnostic): void;
+}
+//#endregion
+//#region ../../lib/diagnostics/src/null-reporter.d.ts
+export declare const nullReporter: DiagnosticReporter;
+//#endregion
+//#region ../../lib/diagnostics/src/presets.d.ts
+/** `'silent'` mode — every diagnostic is ignored. */
+export declare const silentDiagnostics: Diagnostics;
+/** `'warn'` mode — Warning and above print to the console; only `Fatal` throws. */
+export declare const warnDiagnostics: Diagnostics;
+/** `'throw'` mode — Warning prints, **`Error` and above throw**. Note this is
+ *  "errors throw", not "everything throws"; a Warning is still just logged. */
+export declare const throwDiagnostics: Diagnostics;
+//#endregion
+//#region ../../lib/diagnostics/src/resolve-diagnostics.d.ts
+type DiagnosticsMode = 'warn' | 'throw' | 'silent';
+/**
+ * Resolves an `enforcement.diagnostics` value — a preset name, a full `Diagnostics`
+ * instance, or `undefined` — to a concrete `Diagnostics` instance. Lets authors write
+ * `enforcement: { diagnostics: 'warn' }` without importing `Diagnostics` or the presets
+ * themselves.
+ */
+export declare function resolveDiagnostics(value: Diagnostics | DiagnosticsMode | undefined, fallback: Diagnostics): Diagnostics;
+//#endregion
+export type { DefaultPolicyOptions, Diagnostic, DiagnosticInput, DiagnosticPolicy, DiagnosticReporter, DiagnosticSuggestion, DiagnosticsMode, Err, Formatter, Ok, Result, SourceLocation, SourcePosition, ValidationResult };