@charcuterie/ui 0.1.1 → 0.2.0

package/src/index.ts

@@ -31,6 +31,12 @@
  * this package's README has always told it to do.
  */
 
+export type {
+  AccordionHeadingLevel,
+  AccordionItem,
+  AccordionProps,
+} from "./Accordion/Accordion.tsx"
+export { Accordion } from "./Accordion/Accordion.tsx"
 export type {
   AlertProps,
   AlertSize,
@@ -60,6 +66,10 @@ export type {
   EmptyStateSize,
 } from "./EmptyState/EmptyState.tsx"
 export { EmptyState } from "./EmptyState/EmptyState.tsx"
+export type { FieldProps } from "./Field/Field.tsx"
+export { Field } from "./Field/Field.tsx"
+export type { FileDropZoneProps } from "./FileDropZone/FileDropZone.tsx"
+export { FileDropZone } from "./FileDropZone/FileDropZone.tsx"
 export type { IconButtonProps } from "./IconButton/IconButton.tsx"
 export { IconButton } from "./IconButton/IconButton.tsx"
 export type { IntentAppearance } from "./intentStyles.ts"
@@ -76,6 +86,11 @@ export type {
   LiveStatusIndicatorSize,
 } from "./LiveStatusIndicator/LiveStatusIndicator.tsx"
 export { LiveStatusIndicator } from "./LiveStatusIndicator/LiveStatusIndicator.tsx"
+export type {
+  LogLine,
+  LogViewerProps,
+} from "./LogViewer/LogViewer.tsx"
+export { LogViewer } from "./LogViewer/LogViewer.tsx"
 export type {
   MediaTileProps,
   MediaTileRatio,
@@ -83,6 +98,11 @@ export type {
 export { MediaTile } from "./MediaTile/MediaTile.tsx"
 export type { MediaStatus } from "./MediaTile/mediaStatus.ts"
 export { mediaTransitions } from "./MediaTile/mediaStatus.ts"
+export type {
+  MenuItem,
+  MenuProps,
+} from "./Menu/Menu.tsx"
+export { Menu } from "./Menu/Menu.tsx"
 export type {
   ModalProps,
   ModalSize,
@@ -106,11 +126,23 @@ export type {
   SegmentedItem,
 } from "./SegmentedControl/SegmentedControl.tsx"
 export { SegmentedControl } from "./SegmentedControl/SegmentedControl.tsx"
+export type {
+  SelectItem,
+  SelectOption,
+  SelectOptionGroup,
+  SelectProps,
+} from "./Select/Select.tsx"
+export { Select } from "./Select/Select.tsx"
 export type {
   SkeletonProps,
   SkeletonShape,
 } from "./Skeleton/Skeleton.tsx"
 export { Skeleton } from "./Skeleton/Skeleton.tsx"
+export type {
+  SortableTableHeaderProps,
+  SortDirection,
+} from "./SortableTableHeader/SortableTableHeader.tsx"
+export { SortableTableHeader } from "./SortableTableHeader/SortableTableHeader.tsx"
 export type { SpinnerProps } from "./Spinner/Spinner.tsx"
 export { Spinner } from "./Spinner/Spinner.tsx"
 export {
@@ -127,6 +159,17 @@ export type {
   TabsProps,
 } from "./Tabs/Tabs.tsx"
 export { Tabs } from "./Tabs/Tabs.tsx"
+export type { ToastProps } from "./Toast/Toast.tsx"
+export { Toast } from "./Toast/Toast.tsx"
+export type {
+  ToastRecord,
+  ToastRegionProps,
+} from "./Toast/ToastRegion.tsx"
+export { ToastRegion } from "./Toast/ToastRegion.tsx"
+export type { ToastStatus } from "./Toast/toastLifecycle.ts"
+export { toastTransitions } from "./Toast/toastLifecycle.ts"
+export type { TooltipProps } from "./Tooltip/Tooltip.tsx"
+export { Tooltip } from "./Tooltip/Tooltip.tsx"
 export { toClassName } from "./toClassName.ts"
 export type { VisuallyHiddenProps } from "./VisuallyHidden/VisuallyHidden.tsx"
 export { VisuallyHidden } from "./VisuallyHidden/VisuallyHidden.tsx"

package/src/mountStory.testHelpers.ts

@@ -25,16 +25,46 @@ type MountableStory = {
  * drift from it. It is also what triggers the a11y addon's
  * `afterEach`, so every mount here is an axe run.
  */
+/**
+ * Every canvas this helper has created, so the next mount can take
+ * the previous ones out of the document.
+ *
+ * They used to accumulate — one detached-but-attached `<div>` per
+ * test, for the whole file — and nothing noticed for three
+ * milestones, because every component up to M6 lays out **in
+ * flow**: a stale copy sits harmlessly below the live one and every
+ * query is scoped to its own canvas anyway.
+ *
+ * `ToastRegion` is the first `position: fixed` component in the
+ * library, and it broke that immediately. A previous test's toast
+ * stack is pinned to the same corner of the viewport as the live
+ * one, so `userEvent.click` — which clicks by **coordinates** —
+ * drove the wrong element while every query still returned the
+ * right one. The test failed with "the toast did not go away", one
+ * test after the toast it was actually clicking.
+ *
+ * The stale tree is removed rather than unmounted because portable
+ * stories expose no unmount. Detaching is enough: it takes the node
+ * out of the layout, which is the entire problem.
+ */
+const mountedCanvases: HTMLElement[] = []
+
 export const mountStory = async (
   story: MountableStory,
 ): Promise<{
   canvas: Canvas
   canvasElement: HTMLElement
 }> => {
+  for (const previous of mountedCanvases.splice(0)) {
+    previous.remove()
+  }
+
   const canvasElement = document.createElement("div")
 
   document.body.append(canvasElement)
 
+  mountedCanvases.push(canvasElement)
+
   await story.run({ canvasElement })
 
   return { canvas: within(canvasElement), canvasElement }

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)
+      }
+    }
+  },
+)