@epilot/volt-ui-experimental-griffel 0.2.3 → 0.3.0

package/AUTHORING.md

@@ -1,292 +0,0 @@
-# Authoring volt-ui-v2 — what went wrong, and why the rules exist
-
-`AGENTS.md` is the brief: what to do, and it is normative. This is the reasoning: what broke, how it was found,
-and what it cost. Every item here is a defect that actually shipped into the branch, and most of them
-passed source review, a green unit suite and a source-level audit before a rendering comparison caught
-them.
-
-Read this before changing a component or adding one. The single most useful thing in it is the pattern
-at the end: **the same class of mistake recurred four times, and it was never caught by reading.**
-
----
-
-## 1. The engine — four Griffel constraints, all of which fail silently
-
-### 1.1 `&` must be the first token of a selector
-
-Writing `"[data-pressed] &"` reads as "style me when an ancestor is pressed". Griffel does not
-substitute `&` in that position; it prepends its own class to the whole selector and emits:
-
-```css
-.f1y9ypwo[data-pressed] .f1y9ypwo {
-  opacity: 1;
-}
-```
-
-That needs one element to carry the class AND be pressed AND contain a second element with the same
-class. It never matches. No warning, no error, no failing test.
-
-**Cost: fifteen dead declarations across six components**, every one a feature that silently did not
-work — all four of Toast's type colours (every toast looked identical), OptionCard's six
-selected-state glyphs, Label's disabled dimming, Select's chevron rotation.
-
-Only OptionCard's was caught by the visual gate, because it was the only one with a specimen that
-exercised the state. `src/ancestor-selector.test.ts` now forbids the form, and reads source for
-exactly that reason.
-
-**Instead:** declare the rule on the slot of the element that carries the state, and reach the
-descendant by `SLOT_ATTR`:
-
-```ts
-[`&[data-pressed] [${SLOT_ATTR}="option-card-radio-dot"]`]: { opacity: 1 }
-```
-
-If the ancestor belongs to another component, the rule belongs in that component — Label's disabled
-rules live in `field.tsx`. **And there is a real capability loss here:** v1 expresses these with
-Tailwind's `group-data-[…]:` and `peer-disabled:`, which work only because Tailwind emits _global_
-utility classes that can be rooted anywhere. Scoped atomic CSS cannot. A Label used outside a Field,
-next to a disabled input, will not dim.
-
-### 1.2 Declaration order inside a slot encodes precedence
-
-Griffel emits atoms in source order, so a later state selector beats an earlier one. **v1's precedence
-does not come from order** — it comes from Tailwind's utility layer, where `aria-invalid:` beats
-`disabled:` no matter where either sits in the class string.
-
-Transcribing v1's class order therefore inverts the result. Checkbox and Radio both put
-`&[aria-invalid='true']` before `&[data-disabled]`, so a disabled invalid control lost its error
-border to the gray one: 17% and 44% pixel differences on a 16×16 box.
-
-**Put the state that must win last.**
-
-### 1.3 Dedup only happens when the expanded property keys match
-
-OptionCard's card is a `ToggleGroupItem`. Toggle declares `shorthands.paddingInline`; the card
-declared `paddingLeft`/`paddingRight`. Different keys, so both survived and the cascade kept Toggle's
-value — the padding stayed 4px-per-side wrong _after the value itself had been corrected_, which is a
-confusing thing to debug.
-
-Match the neighbour's property shape, not just its value.
-
-### 1.4 A typo'd slot name used to compile
-
-`makeVoltStyles` was generic over the key union:
-
-```
-makeVoltStyles<Slots extends string>(styles: Record<Slots, GriffelStyle>): () => Record<Slots, string>
-```
-
-Inferring a type parameter from `Record<Slots, …>` against an object literal **widens `Slots` to
-`string`**, so the result was `Record<string, string>` and every slot name typechecked — including
-ones that did not exist.
-
-OptionCard read `styles.card` and `styles[layout]` with neither declared. The component rendered with
-**no card styling at all** — v1's card properties had been copied onto the `group` slot and applied to
-the wrong element. `tsc` clean, 322 tests green.
-
-Now generic over the object, so `keyof S` is the real union. It found exactly three errors, all in
-OptionCard: the hole was library-wide, the exploitation was not.
-
----
-
-## 2. Shipping no reset — v2 inherits nothing v1 got for free
-
-v1's components were never written against a reset either. They inherited whatever the _element Radix
-happened to render_ got from the browser's UA stylesheet. Base UI renders different elements, so v2
-inherits nothing.
-
-**Checkbox rendered 2px wide.** Base UI's root is a `<span>`: `display: inline`, where width and
-height **do not apply at all**. v1's Radix root is a `<button>`, which the UA sheet gives
-`inline-block` and `border-box`. v1's own class list declares neither.
-
-Two further subtleties from the same fix:
-
-- `inline-block` specifically, not `inline-flex`. The box is 16×16 either way, but an inline-flex box
-  takes its baseline from its first flex item and sat the line box 2px taller.
-- Declare `boxSizing` where the element type changed, but **not library-wide**. Where v1 also renders
-  a plain div, both arms are already `content-box` and agree — adding `border-box` there would
-  _create_ a difference. 26 slots across 17 components set a size and a border; only the ones the
-  visual gate flagged were actually wrong.
-
-**The reset does exist in production, but do not rely on it.** `epilot360-root-config` imports
-`tailwindcss/preflight.css` globally at the single-spa root. So `box-sizing: border-box` is there for
-an MFE inside the portal — and absent for one bundled standalone. Explicit declarations are no-ops in
-the first case and load-bearing in the second.
-
----
-
-## 3. The primitive layer is Radix — and the Base UI detour is why
-
-**Historical. v2 uses Radix, at v1's exact pins.** Nothing in this section is current guidance; it is
-here because the detour cost real time and the reasoning generalises. `src/lib/auto-portal.tsx`, the
-`InsideMenuGroupContext` wrapper and `collectItemLabels` are all deleted — if you find a reference to
-them, it is stale.
-
-v2 was first built on Base UI and rolled back. The measured case against it:
-
-- **2.1x the size** for the same primitive — tooltip 33.9k vs 16.8k gzip.
-- Its shipped types **forced every consumer onto `@types/react` 19**: 312 errors under 18, none of them
-  in our own logic. It was the sole source of that requirement.
-- It needed wrappers Radix does not — `<Dialog.Portal>` is mandatory, `DropdownMenuLabel` must sit
-  inside a `Menu.Group` — so **every overlay in the package rendered nothing**: nine specimens, blank
-  pages, while 321 tests and four isolation gates stayed green. The package's own tests used the
-  explicit composition Base UI documents, which is exactly why they never hit it.
-
-Two lessons that outlive the decision:
-
-- **Silent acceptance of an unsupported option.** `toast("…", { duration: Infinity })` was accepted,
-  did nothing, and reported nothing; all four toast specimens rendered a bare viewport.
-- **Strictness is not uniformly one way.** v1 **throws** on `OptionCardGroup` without a `type` prop
-  where v2 tolerates it silently — so "v2 is more permissive" is not a safe generalisation, and neither
-  is its opposite.
-
-Radix state attributes are what the code uses now: `data-state="checked" | "on" | "open" | "closed"`,
-and enter/exit transitions key on `data-state` rather than on separate start/end hooks.
-
----
-
-## 4. Rule 0 means v1's OUTPUT, not v1's source
-
-This is the subtlest thing in the package, and it cuts both ways.
-
-**Four v1 production bugs were found here, all one family — the prefixer rewrites definitions and
-misses references:**
-
-1. `--color-level-2`/`-3` point at `--volt-level-2`/`-3`, which nothing defines.
-2. `.volt-text-xs` resolves `line-height: var(--volt-leading, var(--text-xs--line-height))` — the
-   definition ships prefixed, the reference does not, and the unprefixed name is defined nowhere. So
-   **every text utility in v1 computes an invalid line-height and inherits instead.**
-3. Label's `leading-none` never reaches the DOM at all: v1's `cn()` runs tailwind-merge, which treats
-   the later `text-sm` as owning line-height and drops it. Combined with (2), production v1 renders
-   labels at preflight's 1.5 rather than at 1.
-4. ScrollOverflow's viewport declares `[&>div]:!flex` and `[&>div]:!flex-row`, and neither survives
-   the build — so v1's _horizontal_ scroller stacks its children vertically.
-
-**The rule: reproduce the harmless ones, refuse the harmful ones.**
-
-- ScrollOverflow does **not** reproduce bug (4). Matching it would ship a horizontal scroll container
-  that cannot scroll horizontally. That field requires a written reason and prints on every run.
-- Nor does anything reproduce bugs (2) and (3), and that is the one **standing** exception, decided
-  in DECISIONS.md D9. Every slot that sets `fontSize: tokens.text*` also sets the matching
-  `lineHeight: tokens.leading*`, Label included — it follows the `text-sm` its class list actually
-  ships, not the `leading-none` tailwind-merge ate. Bug (2) is not cosmetic: it kills the leading at
-  every one of the seven steps, so reproducing it means shipping a type scale with no vertical
-  rhythm. It is also too wide for an `acceptedDifference` — every specimen containing text would need
-  one — so the VR harness corrects it on the v1 arm instead, once and by name
-  (`V1_DECLARED_LEADING_SHIM` in `vr/run.mjs`, pinned and dated by
-  `vr/v1-leading-references.test.ts`).
-
-Read the exception narrowly. It is about leading and nothing else; everywhere else, output still
-wins.
-
-The same principle settles smaller cases without any bug involved: v1 doesn't style disabled tabs at
-all, so v2's invented `opacity: 0.5` was removed. v1's toast declares `shadow-md` and renders a fully
-transparent one, so v2 has no shadow. v1's OptionCard has a bare Tailwind `border` with no colour
-utility, so its border is `currentColor` — a near-black `rgba(2, 0, 8, 0.88)` that looks like an
-accident and is nevertheless what ships.
-
-**When in doubt, measure the rendered result on both arms. Do not read the class list and infer.**
-
----
-
-## 5. Retiring a dependency inherits its defaults
-
-Toast's width (356px), corner offset (24px), zero-width border and absent shadow were all **sonner**
-defaults, not choices in v1's source. The port replaced sonner's behaviour and kept Tailwind-flavoured
-values — 24rem, 1rem, a real 1px border, a real shadow — so every toast was 28px too wide, 8px too
-close to the corner, and carried an edge and a shadow v1 does not render.
-
-Nothing but a pixel comparison would have said so. The same exposure applies to `cmdk` in Command,
-which has no v1 export to compare against at all.
-
----
-
-## 6. The token layer
-
-- **There was no 0.75rem spacing step, and that is why `spacingElement3` now exists.** The scale ran
-  0.25 / 0.5 / 0.5 / 1 / 1.5 / 2 rem while v1 uses Tailwind's `*-3` freely, so authors reached for the
-  nearest-_sounding_ token (`spacingGroup1`, which is **0.5rem**) and silently lost 4px per side.
-  **That exact mistake was found four times** — Toast, Command, Field, SegmentedControl — which made
-  it a scale problem, not four authoring slips. The step was added; use `tokens.spacingElement3`.
-  This paragraph used to end "use the literal `0.75rem`", which was correct only before the token
-  landed. Sizes are still literals: there is no dimension token family, so `width: "0.75rem"` on an
-  svg is not `spacingElement3` — spacing and size are different axes that share a number.
-- **Line-height tokens are v1's own declared values, and they are applied.** This paragraph used to
-  read "deliberately unused", on the reasoning that applying them diverges from what v1 _renders_
-  (§4 bug 2). That was reversed in DECISIONS.md D9: the divergence is from v1's bug, not from v1, and
-  the harness now measures against v1-as-declared. Pair the leading with the size in the same slot,
-  `fontSize` first. Leave alone the slots that already declare a line-height — those are v1
-  `leading-*` utilities that survived tailwind-merge, so they are v1's output as well as its intent.
-- **The namespace segment is derived from the token values.** `--volt2-<hash>-accent-9` changes
-  whenever any token changes; that is what lets two builds coexist on `:root`. **Never hardcode it.**
-  One test did and broke the moment line-height tokens were added.
-- The accessor is 942 **named exports**, not an object literal, because a bundler cannot drop unused
-  properties of a literal. Worth 6.5 kB gzip to every partial consumer. Authoring is unchanged:
-  `import * as tokens` and keep saying `tokens.accentSolid`.
-
----
-
-## 7. Verifying — where the checks themselves were wrong
-
-A gate that cannot fail is worse than no gate, because it launders an unverified claim. Every one of
-these was a real false pass:
-
-- **Run gates AFTER wiring exports.** `gates/isolation-fixture.tsx` imports the package namespace, so
-  it only inspects what `src/index.ts` exports. Running it on an unwired component is a meaningless
-  pass — that is how Select's `data-slot` violation shipped.
-- **The visual gate reads `dist`.** The first negative control perturbed a padding by 2px and still
-  reported a clean pass, because the edit was in `src`. Staleness is now a hard error.
-- **A blank render is not a match.** Nine overlays rendered nothing while the gate reported
-  "116/124 match", because a blank capture against a mostly-white v1 is a _small_ diff. Uniform
-  captures and thrown pages are now hard failures.
-- **A parse error makes everything pass.** Typechecking a real consumer against v2 reported 0 errors,
-  and a positive control importing a nonexistent name also reported 0 — because the consumer's
-  TypeScript 4.9 could not parse Base UI's `.d.ts`, so the module resolved to an error type. Under TS
-  5.6 the same code reports 148.
-- **A state nobody renders is a state nobody has checked.** That is the whole reason §1.1 needed a
-  source scan on top of the visual gate.
-- **Identical results after a change that should have moved something is a signal.** A patch adding
-  preflight to the harness silently missed its target line; the numbers came back byte-identical and
-  only a direct `box-sizing` measurement caught it.
-- **A test that passes in the file and fails alone has not passed.** Four overlay dismissal tests were
-  green under React 19 and red under React 18, and the component behaved _identically_ in both. Run
-  the suspect test with `-t` before you believe either colour: all four also failed under React 19 in
-  isolation. Three defects were stacked, each masking the next — see §7.1.
-
-### 7.1 The three that hid behind each other
-
-Worth reading as a set, because no single one of them was visible while the others stood:
-
-1. **Testing Library's auto-cleanup never ran.** It self-registers only when the framework's
-   `afterEach` is a global, and neither vitest config sets `globals: true`. Test files had compensated
-   with `document.body.innerHTML = ""`, which detaches nodes without unmounting roots. Radix delivers
-   Escape only to the topmost `DismissableLayer`, so layers left behind by earlier tests swallowed the
-   key. The tell was `data-scroll-locked="3"` on a page containing one dialog.
-   Now registered explicitly in `src/setup.testing-library.ts`, in both configs.
-2. **The removal assertion could not pass on its own merits.** Radix's `Presence` holds a closed node
-   until `animationend`, and jsdom runs no animations. `fireEvent.animationEnd` does not fix it:
-   jsdom implements no `AnimationEvent`, so Testing Library falls back to a plain `Event` and drops
-   `animationName` — precisely the field `Presence` gates on. Construct the event by hand
-   (`src/overlay-test-helpers.ts`). Asserting `data-state="closed"` instead would be vacuous: that
-   attribute is set before `Presence` decides anything.
-3. **Tooltip's Escape raced its own listener.** Radix attaches it in an effect, and the `waitFor`
-   resolved on DOM presence — under React 18, before that effect ran, so the keydown landed with
-   nothing listening. `await act(async () => {})` first. React 19 flushed early enough to hide it.
-
-The general shape: **a version-dependent test result is a claim about the test, until you have shown
-the component behaves differently.** Here it never did.
-
----
-
-## 8. The pattern worth internalising
-
-Four separate times, the same 4px spacing error. Fifteen dead selectors of one shape. Every overlay
-non-functional. A component with no styling at all. None of it was found by reading code — not by
-source review, not by unit tests, not by three source-level audit passes that each found _other_ real
-defects.
-
-All of it was found by rendering both versions and comparing pixels.
-
-So: **when you change a component, run `bun run gate:vr`.** When you add one, add specimens for its
-states, not just its default. And when a check comes back clean on something that has been wrong
-before, find out whether the check can fail at all.

package/dist/packages/volt-runtime/dist/styles/make-styles.js

@@ -1,22 +0,0 @@
-import { getVoltRenderer as r } from "../renderer/index.js";
-import { makeStyles as n } from "../vendor/@griffel/core/src/makeStyles.js";
-import { makeResetStyles as o } from "../vendor/@griffel/core/src/makeResetStyles.js";
-function a(t) {
-  const e = n(
-    t
-  );
-  return function() {
-    return e({ dir: "ltr", renderer: r() });
-  };
-}
-function l(t) {
-  const e = o(t);
-  return function() {
-    return e({ dir: "ltr", renderer: r() });
-  };
-}
-export {
-  l as makeVoltResetStyles,
-  a as makeVoltStyles
-};
-//# sourceMappingURL=make-styles.js.map

package/dist/packages/volt-runtime/dist/styles/make-styles.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"make-styles.js","sources":["../../../../../../volt-runtime/dist/styles/make-styles.js"],"sourcesContent":["import { getVoltRenderer as r } from \"../renderer/index.js\";\nimport { makeStyles as n } from \"../vendor/@griffel/core/src/makeStyles.js\";\nimport { makeResetStyles as l } from \"../vendor/@griffel/core/src/makeResetStyles.js\";\nfunction i(e) {\n  const t = n(\n    e\n  );\n  return function() {\n    return t({ dir: \"ltr\", renderer: r() });\n  };\n}\nfunction c(e) {\n  const t = l(e);\n  return function() {\n    return t({ dir: \"ltr\", renderer: r() });\n  };\n}\nexport {\n  c as makeVoltResetStyles,\n  i as makeVoltStyles\n};\n//# sourceMappingURL=make-styles.js.map\n"],"names":["i","e","t","n","r","c","l"],"mappings":";;;AAGA,SAASA,EAAEC,GAAG;AACZ,QAAMC,IAAIC;AAAAA,IACRF;AAAA,EACJ;AACE,SAAO,WAAW;AAChB,WAAOC,EAAE,EAAE,KAAK,OAAO,UAAUE,EAAC,GAAI;AAAA,EACxC;AACF;AACA,SAASC,EAAEJ,GAAG;AACZ,QAAMC,IAAII,EAAEL,CAAC;AACb,SAAO,WAAW;AAChB,WAAOC,EAAE,EAAE,KAAK,OAAO,UAAUE,EAAC,GAAI;AAAA,EACxC;AACF;"}