@pipelex/mthds-ui 0.24.0 → 0.25.0

package/dist/styles/form-kernel.css

@@ -1,41 +1,41 @@
 /**
- * The form kernel's Tailwind utilities, wrapped in a cascade layer.
- *
- * WHY THE LAYER, AND WHY THIS FILE EXISTS AT ALL
- *
- * `@pipelex/mthds-form/styles.css` is a COMPLETE Tailwind build: preflight plus
- * every utility the kernel's controls use, unprefixed and unscoped. That is the
- * right shape for its intended reader — a host with no Tailwind of its own — and
- * exactly the wrong shape for a host that HAS one. Injected raw into such a host
- * it is a second, later stylesheet full of colliding rules:
- *
- *   - Its bare `.hidden { display: none }` outranks the host's `.sm\:inline`,
- *     because the two have equal specificity and it happens to come last. Every
- *     `class="hidden sm:inline"` label in the host app disappears at every
- *     width. This is not hypothetical: it silently blanked the toolbar and
- *     dialog labels across a consuming application the moment a graph mounted.
- *   - Its preflight re-bases `*, ::before, ::after { border: 0 solid }`. A
- *     shorthand always sets every longhand, so the host's own default border
- *     color is still replaced — but with `currentColor`, which is Tailwind 4's
- *     default. Through kernel 0.7.0 the declaration carried `#e5e7eb` and the
- *     symptom was a pale grey hairline under anything with a border width and
- *     no explicit color class. That symptom is gone as of 0.8.0; the collision
- *     is milder, and the layer settles it either way.
- *
- * Both are the same failure: our sheet loading LATER than the host's and winning
- * ties it has no business winning. A cascade layer settles it by construction —
- * layered rules lose to unlayered rules regardless of source order, so the host
- * keeps every declaration it makes itself, and we still supply the classes it
- * never generated. Nothing here changes for a host with no Tailwind: a layer
- * only decides conflicts, and there are none to decide.
- *
- * The alternative — dropping the import and asking Tailwind hosts to widen their
- * content globs into `node_modules` — is the arrangement that was already
- * failing before the import was added. See the block comments in
- * `../graph/react/index.ts` and `../form/react/index.ts` for why the kernel's
- * classes cannot be left to the host to generate.
- *
- * `theme.css` stays out, layered or not: it defines the semantic tokens
- * (`--background`, `--border`, …) a shadcn host already owns.
+ * The form kernel's prebuilt stylesheet, for a host WITHOUT Tailwind.
+ *
+ * Such a host imports it once, from its own entry:
+ *
+ *   import "@pipelex/mthds-ui/form-kernel.css";
+ *
+ * No JavaScript in this package imports it. From v0.20.0 through v0.24.0 both
+ * React entries injected it into every host, and no single position in the
+ * cascade served a host that has Tailwind of its own; the block comments in
+ * `../graph/react/index.ts` and `../form/react/index.ts` say why.
+ *
+ * WHAT A HOST GETS WITH IT
+ *
+ * `@pipelex/mthds-form/styles.css` is a COMPLETE Tailwind build: every utility
+ * the kernel's controls use, unprefixed and unscoped, and Tailwind's preflight.
+ * The preflight is what lets the controls render with no framework underneath,
+ * and it applies to the whole page, not only to the controls: it resets every
+ * browser default the host does not restate itself, so headings drop to body
+ * size, lists lose their markers, and paragraphs and the body lose their
+ * margins. A dedicated panel such as a webview expects that; a page of ordinary
+ * content that embeds a graph restates the defaults it wants to keep.
+ *
+ * WHY THE LAYER
+ *
+ * Layered rules lose to unlayered rules whatever the source order, so the
+ * host's own rules win every tie against the kernel's utilities and preflight,
+ * even though this sheet may load after the host's. In a host without Tailwind
+ * that is the whole question, which is why the layer stays.
+ *
+ * A HOST WITH TAILWIND 4 MUST NOT IMPORT THIS FILE. It compiles the kernel's
+ * classes itself, through `@pipelex/mthds-ui/tailwind.css` (`./tailwind.css`
+ * beside this file), and this sheet would put a second preflight in its page,
+ * ranked wherever the host's layers leave it.
+ *
+ * `theme.css` stays out: it defines the semantic tokens (`--background`,
+ * `--border`, …) that belong to the host. Since kernel `0.9.0` every utility in
+ * the kernel's sheet reads its token with a fallback, so a host that defines no
+ * tokens renders the kernel's light neutral palette.
  */
 @import "@pipelex/mthds-form/styles.css" layer(mthds-form);

package/dist/styles/tailwind.css

@@ -0,0 +1,51 @@
+/**
+ * Where the form kernel's classes are, for a host with Tailwind 4.
+ *
+ * The kernel's controls are styled with Tailwind utilities that live in its
+ * shipped JavaScript, not in the host's source tree, so a host's build has to be
+ * told to scan it. The kernel's documented Tailwind 4 setup (its
+ * `docs/theming.md`, "A host that runs Tailwind") does that with an `@source`
+ * line naming a path into `node_modules`. This file replaces THAT LINE and
+ * nothing else: a host writes
+ *
+ *   @import "@pipelex/mthds-ui/tailwind.css";
+ *
+ * among its other `@import`s, in any position, since `@source` does not depend
+ * on order. The rest of the kernel's setup stays the host's: `tw-animate-css`,
+ * whose utilities the select popover's and the tooltip's transitions use, and
+ * the `@theme inline` mapping of the shadcn tokens, without which a class such
+ * as `bg-background` compiles to nothing however well the scan found it.
+ *
+ * WHY TWO PATHS
+ *
+ * Tailwind resolves an imported package stylesheet to its REAL path and resolves
+ * that file's `@source` directives relative to it, so both paths below are
+ * relative to where this file lands, `dist/styles/` inside this package. An
+ * explicit `@source` is scanned even inside `node_modules`.
+ *
+ *   - `../../../mthds-form/dist` is the kernel as a sibling of this package:
+ *     in a pnpm virtual store, where every dependency of this package is linked
+ *     beside it, and in an npm tree that hoisted the kernel to the top.
+ *   - `../../node_modules/@pipelex/mthds-form/dist` is the kernel nested under
+ *     this package, which npm does when the host's tree already holds another
+ *     version at the top.
+ *
+ * A path that does not exist is skipped silently, which is why both are listed:
+ * in the layouts pnpm and npm give this package, one of them is the copy of the
+ * kernel this package imports, and the host never names a path into
+ * `node_modules` or declares the kernel itself.
+ *
+ * ONE LAYOUT ESCAPES BOTH
+ *
+ * A tree holding two versions of this package that share a kernel range can
+ * have npm nest one of them, under the workspace or dependency that asked for
+ * it, while the kernel they share is hoisted further up. No path fixed relative
+ * to this file reaches a kernel an arbitrary number of levels above it, so both
+ * candidates are skipped, silently, and the host adds its own `@source` at the
+ * kernel's `dist` (`docs/run-form-panel.md`).
+ *
+ * No JavaScript imports this file, and a host WITHOUT Tailwind never loads it:
+ * it imports `@pipelex/mthds-ui/form-kernel.css` instead. Never both.
+ */
+@source "../../../mthds-form/dist";
+@source "../../node_modules/@pipelex/mthds-form/dist";

package/dist/{types-Cn2FttBC.d.ts → types-Bcsh7Z0U.d.ts}

@@ -524,12 +524,16 @@ declare function toolbarSide(position: ToolbarPosition): ToolbarSide;
  * host's validation lifecycle, not the static analyzer's: `validating` while a
  * verdict is being produced, `valid`/`invalid` once one exists, and `error`
  * when no verdict could be produced at all (validator unavailable, timeout…).
+ * `unvalidated` is for a host with no validator at all, such as a page drawing
+ * a method from its source: no verdict exists or is coming, and the issues are
+ * what reading the source turned up.
  */
 declare const VALIDATION_STATE: {
     readonly VALIDATING: "validating";
     readonly VALID: "valid";
     readonly INVALID: "invalid";
     readonly ERROR: "error";
+    readonly UNVALIDATED: "unvalidated";
 };
 type ValidationState = (typeof VALIDATION_STATE)[keyof typeof VALIDATION_STATE];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/mthds-ui",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Shared graph rendering logic for MTHDS method visualization",
   "license": "MIT",
   "repository": {
@@ -51,7 +51,9 @@
     "./static-graph": {
       "import": "./dist/static-graph/index.js",
       "types": "./dist/static-graph/index.d.ts"
-    }
+    },
+    "./tailwind.css": "./dist/styles/tailwind.css",
+    "./form-kernel.css": "./dist/styles/form-kernel.css"
   },
   "files": [
     "dist"
@@ -76,14 +78,14 @@
     "build-storybook": "storybook build"
   },
   "dependencies": {
-    "@pipelex/mthds-form": "^0.8.0",
+    "@pipelex/mthds-form": "^0.11.0",
     "@xyflow/react": "^12",
     "elkjs": "^0.11.1",
     "smol-toml": "^1.7.0"
   },
   "peerDependencies": {
-    "react": "^19",
-    "react-dom": "^19",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "shiki": "^3.22.0"
   },
   "peerDependenciesMeta": {