@charcuterie/ui 2.18.0 → 3.1.0

package/src/Select/Select.mdx

@@ -17,6 +17,50 @@ see below.
 
 <Controls />
 
+## Sizing: `className` is the wrapper, `controlClassName` is the select
+
+The chevron has to live somewhere, so this renders a wrapper around the native
+`<select>` and positions the chevron against **that wrapper**. `className` therefore
+lands on the wrapper and the `<select>` stays `w-full` inside it:
+
+```tsx
+<Select className="w-44" controlClassName="font-mono" label="Operation" options={OPS} />
+```
+
+means "this control is 176px" — chevron included — which is what a caller writing a
+width already assumes.
+
+It did not used to. `className` reached only the inner element while the wrapper stayed
+`w-full`, so the control shrank and the chevron stayed pinned to the row's right edge:
+
+| | left | right | width |
+| --- | --- | --- | --- |
+| wrapper | 55 | 1128.7 | 1073.6 |
+| select | 55 | 231 | 176 |
+| chevron | 1100.7 | 1116.7 | — |
+
+**869.6px** between the control and its own chevron, measured in mux-magic's DSL rules
+builder, with the control's own text clipping at the same time (`setScriptInfo` →
+`setScriptInfc`). The width never worked; `ui@2.16.0`'s `tailwind-merge` made half of it
+work, which is what made the other half visible
+([#112](https://github.com/Sawtaytoes/charcuterie/issues/112)).
+
+`Select.test.tsx` asserts this as a **measurement** rather than a class-name check —
+every class-name assertion passed while the chevron was 869.6px away, because `w-44`
+really was present, on the element nobody was looking at.
+
+<Canvas of={SelectStories.Sized} />
+
+### What goes where
+
+| | Goes to | For |
+| --- | --- | --- |
+| `className` | the wrapper | width, margin (`ms-auto`), display, position — the outer box |
+| `controlClassName` | the `<select>` | `font-mono` on the option text, a `text-*`, a `bg-*` |
+
+A width in `controlClassName` is the bug again by hand: it desynchronises the inner
+element from the wrapper the chevron is measured against.
+
 ## There is no state kind here, and that is the finding
 
 Every other interactive component in this package owns its state through

package/src/Select/Select.stories.tsx

@@ -132,3 +132,58 @@ export const AllStates: Story = {
     </StoryGrid>
   ),
 }
+
+/**
+ * `className` sizes the **control**, chevron included, because it
+ * lands on the wrapper the chevron is positioned against.
+ *
+ * The first cell is the shape that broke: before this, `w-44`
+ * reached only the inner `<select>` while the wrapper stayed
+ * `w-full`, so the chevron sat at the *row's* right edge — 869.6px
+ * away in mux-magic's rules builder. `controlClassName` is the
+ * inner element, for the things that are not the outer box, and
+ * `font-mono` is the one every caller reaches for.
+ *
+ * The width is still the caller's to get right: `w-44` is narrower
+ * than the longest option here, and a `<select>` clips rather than
+ * wraps. That is why mux-magic measured its widths rather than
+ * guessing them.
+ */
+export const Sized: Story = {
+  args: { label: "Rip profile", options: PROFILES },
+  render: () => (
+    <StoryGrid columns={1}>
+      <StoryCell label="w-44, in a wide row">
+        <Select
+          className="w-44"
+          label="Profile sized"
+          options={PROFILES}
+        />
+      </StoryCell>
+
+      <StoryCell label="w-64, monospaced option text">
+        <Select
+          className="w-64"
+          controlClassName="font-mono"
+          label="Profile monospaced"
+          options={PROFILES}
+        />
+      </StoryCell>
+
+      <StoryCell label="ms-auto, pushed to the end">
+        <Select
+          className="ms-auto w-56"
+          label="Profile pushed"
+          options={PROFILES}
+        />
+      </StoryCell>
+
+      <StoryCell label="default: fills its parent">
+        <Select
+          label="Profile full width"
+          options={PROFILES}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Select/Select.test.tsx

@@ -7,7 +7,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Select.stories.tsx"
 
-const { AllStates, AllVariants, Default } =
+const { AllStates, AllVariants, Default, Sized } =
   composeStories(stories)
 
 test("a select is named, and therefore findable", async () => {
@@ -127,3 +127,91 @@ test("inside a Field, the label does the naming", async () => {
 
   await expect(select).toHaveAttribute("aria-describedby")
 })
+
+/**
+ * The #112 regression test, and it has to be a *measurement*. Every
+ * class-name assertion this could have been passed while the control
+ * was 869.6px away from its own chevron: `w-44` was present, on the
+ * element nobody was looking at.
+ */
+test("a width on className sizes the control, chevron included", async () => {
+  const { canvas } = await mountStory(Sized)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Profile sized",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  const wrapper = select.parentElement as HTMLElement
+  const chevron = wrapper.querySelector("svg") as SVGElement
+
+  const selectBox = select.getBoundingClientRect()
+  const wrapperBox = wrapper.getBoundingClientRect()
+  const chevronBox = chevron.getBoundingClientRect()
+
+  // 11rem. The caller asked for one box, not two of different sizes.
+  await expect(wrapperBox.width).toBe(176)
+
+  await expect(selectBox.width).toBe(wrapperBox.width)
+
+  // The chevron is `end-3` against the wrapper, so this is the whole
+  // bug in one number: it used to read 869.6.
+  await expect(
+    selectBox.right - chevronBox.right,
+  ).toBeCloseTo(12, 1)
+
+  // …and it is inside the control on the other side too, rather than
+  // merely near it.
+  await expect(chevronBox.left).toBeGreaterThan(
+    selectBox.left,
+  )
+})
+
+/**
+ * The other half of the split: an inner-element class still reaches
+ * the inner element, and does not become the wrapper's problem.
+ */
+test("controlClassName reaches the select, not the wrapper", async () => {
+  const { canvas } = await mountStory(Sized)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Profile monospaced",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  const wrapper = select.parentElement as HTMLElement
+
+  await expect(select.className).toContain("font-mono")
+
+  await expect(wrapper.className).not.toContain("font-mono")
+
+  // …and the wrapper is still the one carrying the width.
+  await expect(wrapper.getBoundingClientRect().width).toBe(
+    256,
+  )
+})
+
+/**
+ * The default is unchanged, which is the other half of the fix being
+ * safe: every existing caller passes no width and expects the
+ * control to fill its parent.
+ */
+test("with no className, the control still fills its parent", async () => {
+  const { canvas } = await mountStory(Sized)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Profile full width",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  const wrapper = select.parentElement as HTMLElement
+  const parent = wrapper.parentElement as HTMLElement
+
+  await expect(
+    wrapper.getBoundingClientRect().width,
+  ).toBeCloseTo(parent.getBoundingClientRect().width, 1)
+
+  await expect(
+    select.getBoundingClientRect().width,
+  ).toBeCloseTo(wrapper.getBoundingClientRect().width, 1)
+})

package/src/Select/Select.tsx

@@ -42,7 +42,23 @@ export type SelectProps = Omit<
   ComponentPropsWithRef<"select">,
   "disabled" | "onChange" | "size" | "value"
 > & {
+  /**
+   * Goes on the **wrapper**, which is the box a caller means when
+   * they size a control. See the component docblock — the chevron
+   * is positioned against that wrapper, so a width anywhere else
+   * leaves it behind.
+   */
   className?: string
+  /**
+   * The escape hatch for the inner `<select>` itself, for the
+   * things that genuinely are not the outer box: `font-mono` on the
+   * option text, a `text-*` override, a `bg-*`.
+   *
+   * Sizing does **not** belong here. The inner element is `w-full`
+   * and a width on it desynchronises it from the wrapper the
+   * chevron is pinned to, which is the whole of #112.
+   */
+  controlClassName?: string
   isDisabled?: boolean
   /**
    * The accessible name, when this is **not** inside a `Field`. A
@@ -82,6 +98,25 @@ const getIsGroup = (
  * A styled native `<select>`, and the fleet's fourteen hand-rolled
  * ones collapse onto it.
  *
+ * ### Sizing: `className` is the wrapper, `controlClassName` is the select
+ *
+ * This renders a wrapper around the native `<select>` because the
+ * chevron has to live somewhere, and the chevron is positioned
+ * against that wrapper. `className` therefore lands on the wrapper
+ * and the `<select>` stays `w-full` inside it, so
+ * `className="w-44"` means "this control is 176px" — chevron
+ * included — which is what a caller writing a width already assumes.
+ *
+ * Before this, `className` went to the inner element only. The
+ * wrapper stayed `w-full`, the chevron stayed at *its* edge, and
+ * mux-magic's rules builder measured the gap at **869.6px** with the
+ * control's own text clipping beside it. The width never worked;
+ * `ui@2.16.0`'s `tailwind-merge` only made half of it work and made
+ * the other half visible.
+ *
+ * For the genuinely-inner things — `font-mono` on the option text, a
+ * `bg-*` — there is `controlClassName`.
+ *
  * ### There is no state kind here, and that is the finding
  *
  * Every other interactive component in this package owns its state
@@ -116,6 +151,7 @@ const getIsGroup = (
  */
 export const Select = ({
   className,
+  controlClassName,
   isDisabled = false,
   label,
   onChange,
@@ -125,7 +161,24 @@ export const Select = ({
   value,
   ...selectProps
 }: SelectProps): ReactNode => (
-  <div className="relative inline-grid w-full items-center">
+  <div
+    className={toClassName(
+      "relative inline-grid w-full items-center",
+      // `className` lands HERE, not on the `<select>`, and that is
+      // the fix for #112 rather than a stylistic choice. The chevron
+      // below is `absolute end-3` against this element, so a width
+      // that reaches only the inner control moves the control and
+      // leaves the chevron pinned to the old edge — measured at
+      // 869.6px adrift in mux-magic's rules builder, with the
+      // control's own text clipping at the same time.
+      //
+      // It also matches every other component in this package:
+      // `className` is the outermost box. `ms-auto` — which mux-magic
+      // passes and which did nothing on a `w-full` inner select — is
+      // the tell that callers already believed this.
+      className,
+    )}
+  >
     <select
       {...selectProps}
       aria-label={label}
@@ -145,7 +198,10 @@ export const Select = ({
         "hover:border-border-strong",
         FOCUS_RING_CLASS,
         DISABLED_CLASS,
-        className,
+        // Inner-only, and deliberately not `className`. `w-full`
+        // above keeps this element the same width as the wrapper the
+        // chevron is measured from, so the two can never drift.
+        controlClassName,
       )}
       defaultValue={
         value ??

package/src/argTypes.storyHelpers.ts

@@ -1,4 +1,8 @@
 import { connectionTransitions } from "@charcuterie/logic"
+import {
+  CATEGORICAL_HUES,
+  CATEGORICAL_INDEXES,
+} from "@charcuterie/tokens"
 import type { InputType } from "storybook/internal/types"
 
 import { CONTROL_SIZE_CLASS } from "./controlStyles.ts"
@@ -95,6 +99,41 @@ export const PLACEMENT_OPTIONS = [
 
 export const intentArgType = toChoiceArgType(INTENT_OPTIONS)
 
+/**
+ * `categorical` is the one enumerable prop in the package whose
+ * values are **numbers**, so it cannot go through `toOptions` —
+ * `Object.keys` on a numerically-keyed record returns
+ * `["1", "2", …]`, and a control handing the component `"3"` where
+ * it wants `3` indexes a `Record<CategoricalIndex, …>` with a
+ * string and paints nothing. Reading `CATEGORICAL_INDEXES` keeps
+ * the type and the control agreeing.
+ *
+ * `undefined` leads the list because it is the real default: a
+ * badge with no `categorical` is an `intent` badge, and a control
+ * with no way back to that would make the two props look like a
+ * choice the reader cannot undo.
+ */
+export const CATEGORICAL_OPTIONS = [...CATEGORICAL_INDEXES]
+
+export const categoricalArgType: InputType = {
+  control: { type: "select" },
+  options: [undefined, ...CATEGORICAL_OPTIONS],
+  // The names are `CATEGORICAL_HUES`', not invented here — a picker
+  // that says "3" tells a reader nothing, and `Swatch` already
+  // settled that a colour needs a word attached.
+  mapping: Object.fromEntries(
+    CATEGORICAL_OPTIONS.map((index) => [index, index]),
+  ),
+  table: {
+    type: {
+      summary: CATEGORICAL_OPTIONS.map(
+        (index) =>
+          `${index} (${CATEGORICAL_HUES[index].label})`,
+      ).join(" | "),
+    },
+  },
+}
+
 export const controlSizeArgType = toChoiceArgType(
   CONTROL_SIZE_OPTIONS,
 )

package/src/categoricalStyles.ts

@@ -0,0 +1,244 @@
+/**
+ * One categorical index → class map, the twin of
+ * `intentStyles.ts`.
+ *
+ * Its own file rather than ten more entries in that one, because
+ * the two families are keyed by different things and mean different
+ * things. `intentStyles.ts` opens by explaining that it exists to
+ * delete rip-deck's duplicated `TONE_CLASS` — a *status* map, where
+ * every key is a claim about state. Nothing here is a claim about
+ * anything: an index is a user's pick for a label, and the only
+ * thing a component may do with it is paint it. Keeping them apart
+ * is also what keeps `IntentName` an exhaustive union that
+ * `getAsyncIntent` can switch over.
+ *
+ * **Every class name is written out in full, and that is not
+ * negotiable.** Tailwind v4 scans source text for *complete* class
+ * strings, so `` `bg-categorical-${index}-solid` `` generates
+ * nothing at all — the badge renders unstyled with no error, no
+ * warning, and no failing test unless something checks. Something
+ * does: `tailwindCandidates.test.ts` compiles every literal in this
+ * package through the real Tailwind and fails on any candidate it
+ * cannot generate. Forty lines of near-duplication is the price,
+ * and the alternative is the `--color-danger-9` that shipped in
+ * Docket: a token name that had never existed, resolving to
+ * nothing, painting transparent, and passing every assertion about
+ * whether the element was rendered.
+ */
+
+import type { CategoricalIndex } from "@charcuterie/tokens"
+
+import type { IntentAppearance } from "./intentStyles.ts"
+
+export const CATEGORICAL_APPEARANCE_CLASS: Record<
+  CategoricalIndex,
+  Record<IntentAppearance, string>
+> = {
+  1: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-1-content",
+    outline:
+      "border-categorical-1-border bg-transparent text-categorical-1-content",
+    soft: "border-categorical-1-border bg-categorical-1-surface text-categorical-1-content",
+    solid:
+      "border-transparent bg-categorical-1-solid text-categorical-1-on-solid",
+  },
+  2: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-2-content",
+    outline:
+      "border-categorical-2-border bg-transparent text-categorical-2-content",
+    soft: "border-categorical-2-border bg-categorical-2-surface text-categorical-2-content",
+    solid:
+      "border-transparent bg-categorical-2-solid text-categorical-2-on-solid",
+  },
+  3: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-3-content",
+    outline:
+      "border-categorical-3-border bg-transparent text-categorical-3-content",
+    soft: "border-categorical-3-border bg-categorical-3-surface text-categorical-3-content",
+    solid:
+      "border-transparent bg-categorical-3-solid text-categorical-3-on-solid",
+  },
+  4: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-4-content",
+    outline:
+      "border-categorical-4-border bg-transparent text-categorical-4-content",
+    soft: "border-categorical-4-border bg-categorical-4-surface text-categorical-4-content",
+    solid:
+      "border-transparent bg-categorical-4-solid text-categorical-4-on-solid",
+  },
+  5: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-5-content",
+    outline:
+      "border-categorical-5-border bg-transparent text-categorical-5-content",
+    soft: "border-categorical-5-border bg-categorical-5-surface text-categorical-5-content",
+    solid:
+      "border-transparent bg-categorical-5-solid text-categorical-5-on-solid",
+  },
+  6: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-6-content",
+    outline:
+      "border-categorical-6-border bg-transparent text-categorical-6-content",
+    soft: "border-categorical-6-border bg-categorical-6-surface text-categorical-6-content",
+    solid:
+      "border-transparent bg-categorical-6-solid text-categorical-6-on-solid",
+  },
+  7: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-7-content",
+    outline:
+      "border-categorical-7-border bg-transparent text-categorical-7-content",
+    soft: "border-categorical-7-border bg-categorical-7-surface text-categorical-7-content",
+    solid:
+      "border-transparent bg-categorical-7-solid text-categorical-7-on-solid",
+  },
+  8: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-8-content",
+    outline:
+      "border-categorical-8-border bg-transparent text-categorical-8-content",
+    soft: "border-categorical-8-border bg-categorical-8-surface text-categorical-8-content",
+    solid:
+      "border-transparent bg-categorical-8-solid text-categorical-8-on-solid",
+  },
+  9: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-9-content",
+    outline:
+      "border-categorical-9-border bg-transparent text-categorical-9-content",
+    soft: "border-categorical-9-border bg-categorical-9-surface text-categorical-9-content",
+    solid:
+      "border-transparent bg-categorical-9-solid text-categorical-9-on-solid",
+  },
+  10: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-10-content",
+    outline:
+      "border-categorical-10-border bg-transparent text-categorical-10-content",
+    soft: "border-categorical-10-border bg-categorical-10-surface text-categorical-10-content",
+    solid:
+      "border-transparent bg-categorical-10-solid text-categorical-10-on-solid",
+  },
+}
+
+/**
+ * Hover, split out for exactly the reason `INTENT_HOVER_CLASS` is:
+ * most things wearing a colour are not interactive. A label pill in
+ * a task list that lightens under the cursor is telling the user it
+ * can be clicked, and a `Badge` cannot be. So an interactive
+ * component opts in, and a static one cannot accidentally opt in.
+ *
+ * `solid` hovers toward `solidHover`, which for this family is
+ * **brighter** rather than deeper — the fill carries a near-black
+ * label, so it moves away from it in the opposite direction to an
+ * intent's white-labelled fill.
+ */
+export const CATEGORICAL_HOVER_CLASS: Record<
+  CategoricalIndex,
+  Record<IntentAppearance, string>
+> = {
+  1: {
+    ghost: "hover:bg-categorical-1-surface",
+    outline: "hover:bg-categorical-1-surface",
+    soft: "hover:bg-categorical-1-surface-hover",
+    solid: "hover:bg-categorical-1-solid-hover",
+  },
+  2: {
+    ghost: "hover:bg-categorical-2-surface",
+    outline: "hover:bg-categorical-2-surface",
+    soft: "hover:bg-categorical-2-surface-hover",
+    solid: "hover:bg-categorical-2-solid-hover",
+  },
+  3: {
+    ghost: "hover:bg-categorical-3-surface",
+    outline: "hover:bg-categorical-3-surface",
+    soft: "hover:bg-categorical-3-surface-hover",
+    solid: "hover:bg-categorical-3-solid-hover",
+  },
+  4: {
+    ghost: "hover:bg-categorical-4-surface",
+    outline: "hover:bg-categorical-4-surface",
+    soft: "hover:bg-categorical-4-surface-hover",
+    solid: "hover:bg-categorical-4-solid-hover",
+  },
+  5: {
+    ghost: "hover:bg-categorical-5-surface",
+    outline: "hover:bg-categorical-5-surface",
+    soft: "hover:bg-categorical-5-surface-hover",
+    solid: "hover:bg-categorical-5-solid-hover",
+  },
+  6: {
+    ghost: "hover:bg-categorical-6-surface",
+    outline: "hover:bg-categorical-6-surface",
+    soft: "hover:bg-categorical-6-surface-hover",
+    solid: "hover:bg-categorical-6-solid-hover",
+  },
+  7: {
+    ghost: "hover:bg-categorical-7-surface",
+    outline: "hover:bg-categorical-7-surface",
+    soft: "hover:bg-categorical-7-surface-hover",
+    solid: "hover:bg-categorical-7-solid-hover",
+  },
+  8: {
+    ghost: "hover:bg-categorical-8-surface",
+    outline: "hover:bg-categorical-8-surface",
+    soft: "hover:bg-categorical-8-surface-hover",
+    solid: "hover:bg-categorical-8-solid-hover",
+  },
+  9: {
+    ghost: "hover:bg-categorical-9-surface",
+    outline: "hover:bg-categorical-9-surface",
+    soft: "hover:bg-categorical-9-surface-hover",
+    solid: "hover:bg-categorical-9-solid-hover",
+  },
+  10: {
+    ghost: "hover:bg-categorical-10-surface",
+    outline: "hover:bg-categorical-10-surface",
+    soft: "hover:bg-categorical-10-surface-hover",
+    solid: "hover:bg-categorical-10-solid-hover",
+  },
+}
+
+/**
+ * The fill on its own, for the parts of a component that are a dot
+ * or a bar rather than a box — the swatch beside a label in a
+ * picker, a series marker on a chart. Same values, no border and no
+ * hover, because neither of those is a surface anyone can point at.
+ */
+export const CATEGORICAL_SOLID_FILL_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "bg-categorical-1-solid",
+  2: "bg-categorical-2-solid",
+  3: "bg-categorical-3-solid",
+  4: "bg-categorical-4-solid",
+  5: "bg-categorical-5-solid",
+  6: "bg-categorical-6-solid",
+  7: "bg-categorical-7-solid",
+  8: "bg-categorical-8-solid",
+  9: "bg-categorical-9-solid",
+  10: "bg-categorical-10-solid",
+}
+
+/** The same ten as text, for a glyph or a dot's ring. */
+export const CATEGORICAL_CONTENT_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "text-categorical-1-content",
+  2: "text-categorical-2-content",
+  3: "text-categorical-3-content",
+  4: "text-categorical-4-content",
+  5: "text-categorical-5-content",
+  6: "text-categorical-6-content",
+  7: "text-categorical-7-content",
+  8: "text-categorical-8-content",
+  9: "text-categorical-9-content",
+  10: "text-categorical-10-content",
+}