@charcuterie/ui 0.1.1 → 1.0.0

package/src/slotProps.ts

@@ -0,0 +1,143 @@
+import type { InputHTMLAttributes } from "react"
+
+/**
+ * The props a **cloning ancestor** injects into the control below it.
+ *
+ * `Field` and `Tooltip` both take one child and `cloneElement` onto
+ * it — "cloned, not wrapped", which is what lets a `Field` go around
+ * an `<input>`, a `Select`, or an app's own control without changing
+ * that control's layout. The contract has a hole in it the moment two
+ * of them are nested:
+ *
+ * ```tsx
+ * <Field label="Pattern" isRequired>
+ *   <Tooltip label="A JavaScript regular expression">
+ *     <input />
+ *   </Tooltip>
+ * </Field>
+ * ```
+ *
+ * `Field` clones onto the **`Tooltip` element**, so `id`,
+ * `aria-describedby`, `aria-invalid` and `required` are handed to a
+ * component that declares none of them — and `cloneElement` does not
+ * care. React drops them without a warning, TypeScript never sees
+ * them (`Children.only` returns a `ReactElement` with `any` props),
+ * every test still passes, and the render is pixel-identical. The
+ * `<label>` then points at an `id` that is nowhere in the document.
+ *
+ * **Silent prop-dropping is the worst version of this**, so the rule
+ * is: *a slot component is a pass-through*. Anything in `SlotProps`
+ * that arrives from above is forwarded to the child this component
+ * clones onto, so a chain of slots behaves like the one control at
+ * the bottom of it.
+ *
+ * ### The list is closed, the forwarding is not
+ *
+ * Worth being exact, because the two are easy to conflate. This type
+ * is a closed list of five keys rather than an index signature: it is
+ * exactly the wiring `Field` writes plus the wiring `Tooltip` writes,
+ * it is greppable, and it is the set whose **merge semantics are
+ * defined** — which for four of them is last-write-wins and for
+ * `aria-describedby` is a join.
+ *
+ * The *runtime* forwards everything. Both components collect their
+ * received props with a rest spread and `mergeSlotProps` starts from
+ * `...receivedProps`, so an ancestor's `onPointerEnter`, its
+ * `onFocus`, its `ref` — none of which are named here — reach the
+ * control at the bottom too. That is not an oversight, it is load
+ * bearing: a `Tooltip` around a `Field` hands down `useHover`,
+ * `useFocus`, `useDismiss` and `refs.setReference`, and a `Field`
+ * that forwarded only the five keys below would leave the tip with no
+ * trigger and no anchor. A closed *runtime* filter would be
+ * mux-magic's `FieldTooltip` defect rebuilt inside the fix for it.
+ *
+ * The five keys, and who writes them:
+ *
+ * | Key | Written by |
+ * | --- | --- |
+ * | `aria-describedby` | `Field` (its description and its error) **and** `Tooltip` (its tip) — the one key that is a list, and the reason `mergeSlotProps` exists |
+ * | `aria-invalid` | `Field`, derived from `error` being present |
+ * | `aria-required` | `Field`, from `isRequired` — the announced constraint, for a composite control the browser does not validate |
+ * | `id` | `Field`, so its `<label htmlFor>` has something to point at. A caller may also pass one directly, which is how a consumer pins a stable id for a deep link or an autofill hint |
+ * | `required` | `Field`, from `isRequired` — the constraint the browser validates |
+ *
+ * ### Why these are `Pick`ed and not written out
+ *
+ * Three of the five are booleans whose names cannot start with `is`
+ * or `has`, because they are not our names — they are the DOM's, and
+ * they are spread onto a DOM node verbatim. The house rule has
+ * [no carve-out](../../../docs/decisions/2026-07-29-is-has-rule-has-no-external-api-carve-out.md)
+ * for that: a *type property* is a shape we own, an object literal
+ * key is someone else's contract, and no `eslint-disable` is
+ * available because unused disable directives are themselves an
+ * error.
+ *
+ * So this type does not declare a shape. It **selects** one out of
+ * React's own `InputHTMLAttributes`, which is the honest description
+ * of what it is: five keys of the props React already types for an
+ * `<input>`, forwarded unchanged. The same reasoning as the
+ * `Record<string, boolean>` in `createReactAdapter` — we are not
+ * describing React's shape, we are naming the keys of it we touch —
+ * and it has the side benefit that `aria-invalid` gets React's real
+ * type (`"grammar"` and `"spelling"` are legal values) rather than
+ * the `boolean` a hand-written version would have narrowed it to.
+ */
+export type SlotProps = Pick<
+  InputHTMLAttributes<HTMLElement>,
+  | "aria-describedby"
+  | "aria-invalid"
+  | "aria-required"
+  | "id"
+  | "required"
+>
+
+/**
+ * Merge what arrived from above with what this component writes
+ * itself.
+ *
+ * Everything here is a single value and last-write-wins is correct
+ * for it — **except `aria-describedby`, which is a list**. Two slot
+ * components each writing their own onto one control is the entire
+ * nesting problem in one attribute: a `Field` naming its description
+ * and its error, and a `Tooltip` naming its tip. A plain spread keeps
+ * one of them and loses the other, which is the same silent drop by a
+ * shorter route.
+ *
+ * **Outer first.** A screen reader reads the list in order, and the
+ * field's own description and error are the control's primary
+ * explanation; a tip is supplementary by construction. The ordering
+ * inside a single `Field` — description, then error — is `Field`'s
+ * own concern and is unaffected.
+ *
+ * `undefined` in `ownProps` is *absence*, not an instruction to
+ * clear. Both callers spell their optional wiring as
+ * `isRequired || undefined`, so a plain spread would let an inner
+ * `Field` with no error erase an outer one's `aria-invalid` — the
+ * same silent drop, one level down.
+ */
+export const mergeSlotProps = <
+  OwnProps extends Record<string, unknown>,
+>(
+  receivedProps: SlotProps,
+  ownProps: OwnProps,
+): OwnProps & SlotProps => {
+  const definedOwnProps = Object.fromEntries(
+    Object.entries(ownProps).filter(
+      ([, value]) => value !== undefined,
+    ),
+  ) as OwnProps
+
+  const describedBy = [
+    receivedProps["aria-describedby"],
+    ownProps["aria-describedby"],
+  ]
+    .filter(Boolean)
+    .join(" ")
+
+  return {
+    ...receivedProps,
+    ...definedOwnProps,
+    "aria-describedby":
+      describedBy === "" ? undefined : describedBy,
+  }
+}

package/src/sourceRules.test.ts

@@ -1,14 +1,20 @@
 /**
- * The three rules about this package's source that no compiler and no
- * axe run can see.
+ * The rules about this package's source — and about the shape of the
+ * workspace around it — that no compiler and no axe run can see.
  *
- * All three come straight from the plan's verification list, and each
- * one is a thing the fleet does today that the library exists to
- * stop.
+ * They come straight from the plan's verification list, and each one
+ * is a thing the fleet does today that the library exists to stop.
+ *
+ * The last two reach past `@charcuterie/ui` into its siblings on
+ * purpose. `ui` sits at the top of the dependency graph, so it is the
+ * one package whose tests can see all three at once — which is why
+ * the plan's cross-package assertions live here rather than in a
+ * `packages/conformance` of their own
+ * ([decision](../../../docs/decisions/2026-07-31-conformance-is-not-a-package.md)).
  */
 
 import { readdir, readFile } from "node:fs/promises"
-import { join, relative, resolve } from "node:path"
+import { dirname, join, relative, resolve } from "node:path"
 
 import { expect, test } from "vitest"
 
@@ -16,6 +22,24 @@ const sourceDirectory = resolve(import.meta.dirname)
 
 const packageDirectory = resolve(sourceDirectory, "..")
 
+const packagesDirectory = resolve(packageDirectory, "..")
+
+type PackageManifest = {
+  dependencies?: Record<string, string>
+  exports?: Record<string, string | { source?: string }>
+  peerDependencies?: Record<string, string>
+}
+
+const readManifest = async (
+  name: string,
+): Promise<PackageManifest> =>
+  JSON.parse(
+    await readFile(
+      join(packagesDirectory, name, "package.json"),
+      "utf8",
+    ),
+  ) as PackageManifest
+
 const getSourceFiles = async (
   directory: string,
 ): Promise<{ contents: string; file: string }[]> => {
@@ -250,12 +274,23 @@ test("the barrel is the only place components are re-exported", async () => {
   // than app-specific: `Alert` (rip-deck spells it four times, twice
   // with a byte-identical `TONE_CLASS`) and `SegmentedControl`.
   //
-  // `TabTrigger` and `SegmentedOption` are deliberately not in this
-  // count and not exported. Each is its own component's member —
-  // its own file only because both registrations are effects and an
-  // effect cannot run in a loop — and the `<Name>/<Name>.tsx`
-  // pattern this regex matches is what keeps them out.
-  expect(componentNames.length).toBe(16)
+  // M6 adds the nine P1 components: `Accordion`, `Field`,
+  // `FileDropZone`, `LogViewer`, `Menu`, `Select`,
+  // `SortableTableHeader`, `Toast`, and `Tooltip`.
+  //
+  // `TabTrigger`, `SegmentedOption`, `AccordionSection`, and
+  // `MenuAction` are deliberately not in this count and not
+  // exported. Each is its own component's member — its own file only
+  // because both registrations are effects and an effect cannot run
+  // in a loop — and the `<Name>/<Name>.tsx` pattern this regex
+  // matches is what keeps them out.
+  //
+  // `ToastRegion` is the one exception worth naming: it *is*
+  // exported, and it lives in `Toast/` rather than owning a
+  // directory because a region with no toasts in it is not a thing
+  // anybody renders. It is therefore outside this count by the same
+  // rule, and the barrel assertion below does not reach it.
+  expect(componentNames.length).toBe(25)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)
@@ -267,37 +302,193 @@ test("dependency direction is tokens ← logic ← ui", async () => {
   // depend on both; `logic` may depend on `tokens`; `tokens` depends
   // on nothing, which is what lets `castkit/packages/views` read a
   // colour without a React tree.
-  const readPackage = async (name: string) =>
-    JSON.parse(
-      await readFile(
-        join(packageDirectory, "..", name, "package.json"),
-        "utf8",
-      ),
-    ) as {
-      dependencies?: Record<string, string>
-      peerDependencies?: Record<string, string>
-    }
-
-  const getCharcuterieDependencies = (manifest: {
-    dependencies?: Record<string, string>
-    peerDependencies?: Record<string, string>
-  }) =>
+  const getCharcuterieDependencies = (
+    manifest: PackageManifest,
+  ) =>
     Object.keys({
       ...manifest.dependencies,
       ...manifest.peerDependencies,
     }).filter((name) => name.startsWith("@charcuterie/"))
 
   expect(
-    getCharcuterieDependencies(await readPackage("tokens")),
+    getCharcuterieDependencies(
+      await readManifest("tokens"),
+    ),
   ).toEqual([])
 
   expect(
-    getCharcuterieDependencies(await readPackage("logic")),
+    getCharcuterieDependencies(await readManifest("logic")),
   ).toEqual([])
 
   expect(
     getCharcuterieDependencies(
-      await readPackage("ui"),
+      await readManifest("ui"),
     ).sort(),
   ).toEqual(["@charcuterie/logic", "@charcuterie/tokens"])
 })
+
+/**
+ * What every published entry point is allowed to reach at runtime.
+ *
+ * This is what survives of the plan's `@charcuterie/conformance`
+ * package — "builds React19+TWv4 / Preact / Satori profiles" — once
+ * the three profiles are checked against what the library actually
+ * became. Two of them are already built and gated by name (`docs` is
+ * the React 19 + Tailwind v4 build; `logic`'s five-adapter suite is
+ * the Preact one), and the third has no components to render because
+ * the ePaper-safe subset was never built. What no gate covered is the
+ * claim each of those profiles actually rests on: **which runtime a
+ * consumer is forced to install by importing a given entry point.**
+ * That is the assertion below.
+ *
+ * Each of these numbers is load-bearing somewhere:
+ *
+ * - `tokens` reaches **nothing**. `castkit/packages/views` renders
+ *   through Satori and must read a colour without a React tree.
+ * - `logic/core` reaches **nothing**, and `logic/preact` never
+ *   reaches `react` — `preact/compat` is most of `slatecast`'s 60 KB
+ *   gz budget, and an accidental `react` import there is a bundle
+ *   blow-up that typechecks.
+ * - `ui/testing` reaches **nothing**, which is the promise
+ *   `expectAgentDrivable.ts` makes in prose: it ships for consumers
+ *   to hold *their* components to, and a published package must not
+ *   drag a test framework into an app's dependency graph.
+ *
+ * A type-only import counts. It is erased from the bundle but not
+ * from the `.d.ts`, so a consumer still needs the package installed
+ * for their own typecheck to pass.
+ */
+const ENTRY_POINT_RUNTIMES: Record<
+  string,
+  Record<string, string[]>
+> = {
+  logic: {
+    ".": ["react"],
+    "./core": [],
+    "./jotai": ["jotai"],
+    "./preact": ["preact", "preact/hooks"],
+    "./signals": ["@preact/signals-core"],
+  },
+  tokens: {
+    ".": [],
+    "./epaper": [],
+  },
+  ui: {
+    ".": [
+      "@charcuterie/logic",
+      "@charcuterie/tokens",
+      "@floating-ui/react",
+      "react",
+    ],
+    "./testing": [],
+    "./tokens": ["@charcuterie/tokens"],
+  },
+}
+
+/**
+ * Every bare specifier reachable from `entryFile`, following relative
+ * imports and stopping at package boundaries.
+ *
+ * Every relative import in this workspace carries its extension, so
+ * "resolution" is a `join` — no `.js`/`index` guessing, and a typo
+ * fails loudly as a missing file rather than silently pruning the
+ * graph.
+ */
+const collectRuntimeImports = async (entryFile: string) => {
+  const visited = new Set<string>()
+
+  const bareSpecifiers = new Set<string>()
+
+  const visit = async (file: string) => {
+    if (visited.has(file)) {
+      return
+    }
+
+    visited.add(file)
+
+    // Template literals go too. `createStatus`'s error message
+    // spells `from "${current}"`, which is prose about a state
+    // machine and not an import of a package called `${current}`.
+    const contents = stripComments(
+      await readFile(file, "utf8"),
+    ).replace(/`(?:[^`\\]|\\.)*`/g, "")
+
+    const specifiers = [
+      ...contents.matchAll(/\bfrom\s+"([^"]+)"/g),
+      ...contents.matchAll(/\bimport\s+"([^"]+)"/g),
+    ].map(([, specifier]) => specifier as string)
+
+    for (const specifier of specifiers) {
+      if (!specifier.startsWith(".")) {
+        bareSpecifiers.add(specifier)
+
+        continue
+      }
+
+      if (/\.css$/.test(specifier)) {
+        continue
+      }
+
+      await visit(resolve(dirname(file), specifier))
+    }
+  }
+
+  await visit(entryFile)
+
+  return [...bareSpecifiers].sort()
+}
+
+test.each(Object.keys(ENTRY_POINT_RUNTIMES))(
+  "every @charcuterie/%s entry point reaches only its own runtime",
+  async (packageName) => {
+    const manifest = await readManifest(packageName)
+
+    const entryPoints = Object.entries(
+      manifest.exports ?? {},
+    ).flatMap(([name, target]) =>
+      typeof target === "object" && target.source
+        ? [[name, target.source] as const]
+        : [],
+    )
+
+    // The table is exhaustive, so a new entry point cannot land
+    // without somebody deciding what it is allowed to pull in.
+    expect(
+      entryPoints.map(([name]) => name).sort(),
+    ).toEqual(
+      Object.keys(
+        ENTRY_POINT_RUNTIMES[packageName] ?? {},
+      ).sort(),
+    )
+
+    const declared = Object.keys({
+      ...manifest.dependencies,
+      ...manifest.peerDependencies,
+    })
+
+    for (const [name, source] of entryPoints) {
+      const reached = await collectRuntimeImports(
+        join(packagesDirectory, packageName, source),
+      )
+
+      expect({
+        entryPoint: `${packageName}${name.slice(1)}`,
+        reached,
+      }).toEqual({
+        entryPoint: `${packageName}${name.slice(1)}`,
+        reached: ENTRY_POINT_RUNTIMES[packageName]?.[name],
+      })
+
+      // And nothing reached is a phantom dependency —
+      // `preact/hooks` is declared as `preact`, which is the unit an
+      // install actually has.
+      for (const specifier of reached) {
+        const packageOfSpecifier = specifier.startsWith("@")
+          ? specifier.split("/").slice(0, 2).join("/")
+          : specifier.split("/")[0]
+
+        expect(declared).toContain(packageOfSpecifier)
+      }
+    }
+  },
+)