@charcuterie/ui 4.26.2 → 4.27.1

package/src/ColorPicker/ColorPicker.mdx

@@ -0,0 +1,70 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks"
+
+import * as ColorPickerStories from "./ColorPicker.stories.tsx"
+
+<Meta of={ColorPickerStories} />
+
+# ColorPicker
+
+A named color from the app's list, or a color of the person's own. The presets are a
+searchable `Combobox`, each row a `Swatch` and its name; an optional **Custom color…** row
+opens a panel with the browser's color wheel and a hex field.
+
+<Canvas of={ColorPickerStories.Playground} />
+
+## Props
+
+<Controls />
+
+## When to use it, and when not
+
+| You have | Use |
+| --- | --- |
+| A palette the **app** owns, maybe plus colors a person makes up | `ColorPicker` |
+| A choice from the library's ten `categorical` hues | A row of `Swatch` buttons over `--color-categorical-<n>-solid`, as Docket's `CategoricalPicker` does |
+| A color that arrived from the world and is only shown | `Swatch` |
+
+The presets are data, so the result is a `Swatch`-class color, not a token: it does not
+re-theme and the library cannot contrast-check it. That is why `getColorError` exists. The
+app knows where the color is drawn and what it has to clear; the component only shows the
+app's sentence and refuses to apply.
+
+## Typing narrows the list
+
+A palette worth offering is long, and siblings may all want a different pink. Typing a name
+narrows the rows to that family; typing a hex code finds its preset. The **Custom color…**
+row is always listed, whatever the search says, and a valid code in the search opens the
+custom panel on that code.
+
+<Canvas of={ColorPickerStories.Interactive} />
+
+## The custom panel
+
+The browser's `<input type="color">` is allowed here and only here. It is the custom
+**mode**, inside a panel this component owns — never the whole picker. The wheel, the
+eyedropper, and the sliders are worth keeping, and the presets are what the native control
+alone could never offer.
+
+Nothing is applied while a person drags the wheel. The panel holds a draft: **Use color** or
+Enter applies it, and Escape or **Cancel** drops it. A custom color answers `#RRGGBB` in
+upper case, so the app stores one spelling for one color.
+
+<Canvas of={ColorPickerStories.CustomPanel} />
+
+## The trigger says the name, or the code
+
+`"Color: Hot Pink"` for a preset and `"Color: #C2185B"` for a custom color. The visible text
+is in the accessible name (WCAG 2.5.3), as with `Picker`. Query it as:
+
+```tsx
+getByRole("button", { name: /^Color: / })
+```
+
+<Canvas of={ColorPickerStories.AllStates} />
+
+## Inside a `Field`
+
+`Field` clones its `id` and `aria-describedby` onto the trigger button, and the trigger
+stretches to the container with the swatch and name at the start and the chevron at the end.
+
+<Canvas of={ColorPickerStories.Responsive} />

package/src/ColorPicker/ColorPicker.stories.tsx

@@ -0,0 +1,289 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+import { userEvent, within } from "storybook/test"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
+import type { ColorPreset } from "./ColorPicker.tsx"
+import { ColorPicker } from "./ColorPicker.tsx"
+import { parseHexColor } from "./parseHexColor.ts"
+
+/**
+ * A palette with several shades of one hue on purpose: the case that
+ * made this a searchable list is a family where every child wants a
+ * different pink.
+ */
+const PRESETS: ColorPreset[] = [
+  { name: "Red", value: "#E63946" },
+  {
+    keywords: ["pink", "red"],
+    name: "Raspberry",
+    value: "#DB2777",
+  },
+  {
+    keywords: ["pink"],
+    name: "Hot Pink",
+    value: "#FF006E",
+  },
+  { keywords: ["pink"], name: "Blush", value: "#FB7185" },
+  {
+    keywords: ["pink"],
+    name: "Bubblegum",
+    value: "#FF69B4",
+  },
+  {
+    keywords: ["pink"],
+    name: "Cotton Candy",
+    value: "#F9A8D4",
+  },
+  {
+    keywords: ["purple"],
+    name: "Lavender",
+    value: "#A78BFA",
+  },
+  { name: "Purple", value: "#8338EC" },
+  { name: "Blue", value: "#3A86FF" },
+  {
+    keywords: ["green", "blue"],
+    name: "Teal",
+    value: "#2A9D8F",
+  },
+  { name: "Green", value: "#22C55E" },
+  { name: "Yellow", value: "#FFBE0B" },
+  { name: "Orange", value: "#FB5607" },
+  { name: "Brown", value: "#B5651D" },
+]
+
+/**
+ * A stand-in for an app's own rule. This one refuses grays and
+ * near-whites, the way a reader board that draws the color on a dark
+ * panel would.
+ */
+const getStoryColorError = (hex: string): null | string => {
+  const digits = (parseHexColor(hex) ?? "").slice(1)
+  const channels = [0, 2, 4].map(
+    (start) =>
+      Number.parseInt(digits.slice(start, start + 2), 16) /
+      255,
+  )
+  const highest = Math.max(...channels)
+  const lowest = Math.min(...channels)
+
+  if (highest - lowest < 0.2) {
+    return "Pick a color with more hue. Gray, white, and black do not show on the board."
+  }
+
+  return null
+}
+
+const meta = {
+  title: "Components/Controls/ColorPicker",
+  component: ColorPicker,
+  parameters: { layout: "padded" },
+  argTypes: {
+    size: controlSizeArgType,
+  },
+  args: {
+    isCustomAllowed: true,
+    label: "Color",
+    onChange: () => {},
+    presets: PRESETS,
+  },
+} satisfies Meta<typeof ColorPicker>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ColorPickerHarness = ({
+  hasColorRule = false,
+  initialValue,
+  isCustomAllowed = true,
+  label,
+}: {
+  hasColorRule?: boolean
+  initialValue?: string
+  isCustomAllowed?: boolean
+  label: string
+}): ReactNode => {
+  const [value, setValue] = useState(initialValue)
+
+  return (
+    <div className="flex flex-col gap-2">
+      <ColorPicker
+        getColorError={
+          hasColorRule ? getStoryColorError : undefined
+        }
+        isCustomAllowed={isCustomAllowed}
+        label={label}
+        onChange={setValue}
+        presets={PRESETS}
+        value={value}
+      />
+      <p className="text-content-muted text-xs">
+        Value: {value ?? "none"}
+      </p>
+    </div>
+  )
+}
+
+/** A preset chosen, custom colors allowed, and an app rule. */
+export const Playground: Story = {
+  parameters: playgroundParameters,
+  render: () => (
+    <ColorPickerHarness
+      hasColorRule
+      initialValue="#FF006E"
+      label="Color"
+    />
+  ),
+}
+
+/** The three sizes, each reading a density-aware control height. */
+export const AllVariants: Story = {
+  render: () => (
+    <StorySection title="Sizes">
+      <StoryRow>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <ColorPicker
+            key={size}
+            label={`Color ${size}`}
+            onChange={() => {}}
+            presets={PRESETS}
+            size={size}
+            value="#3A86FF"
+          />
+        ))}
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+/**
+ * A preset, a custom color (the trigger reads the code), nothing chosen
+ * yet, presets only, and disabled.
+ */
+export const AllStates: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <StorySection title="A preset">
+        <StoryRow>
+          <ColorPickerHarness
+            initialValue="#FF69B4"
+            label="Preset color"
+          />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="A custom color reads its code">
+        <StoryRow>
+          <ColorPickerHarness
+            initialValue="#C2185B"
+            label="Custom color"
+          />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="Nothing chosen">
+        <StoryRow>
+          <ColorPickerHarness label="Empty color" />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="Presets only">
+        <StoryRow>
+          <ColorPickerHarness
+            initialValue="#22C55E"
+            isCustomAllowed={false}
+            label="Presets-only color"
+          />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="Disabled">
+        <StoryRow>
+          <ColorPicker
+            isDisabled
+            label="Disabled color"
+            onChange={() => {}}
+            presets={PRESETS}
+            value="#8338EC"
+          />
+        </StoryRow>
+      </StorySection>
+    </div>
+  ),
+}
+
+/**
+ * The custom panel, opened: the browser's color wheel beside a hex
+ * field, and an app rule refusing a gray.
+ */
+export const CustomPanel: Story = {
+  render: () => (
+    <ColorPickerHarness
+      hasColorRule
+      initialValue="#808080"
+      label="Rule color"
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+
+    await userEvent.click(
+      canvas.getByRole("button", {
+        name: "Rule color: #808080",
+      }),
+    )
+
+    await userEvent.click(
+      within(canvasElement.ownerDocument.body).getByRole(
+        "option",
+        { name: "Custom color…" },
+      ),
+    )
+  },
+}
+
+/**
+ * Drive it: open, type "pink" to narrow the list, choose one, then
+ * choose "Custom color…" and apply a code of your own.
+ */
+export const Interactive: Story = {
+  render: () => (
+    <ColorPickerHarness
+      hasColorRule
+      initialValue="#3A86FF"
+      label="Interactive color"
+    />
+  ),
+}
+
+/**
+ * Inside a `Field` the trigger stretches to the container, and a long
+ * name truncates rather than pushing the chevron out.
+ */
+export const Responsive: Story = {
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <Field label={`Color at ${width}`}>
+          <ColorPicker
+            isCustomAllowed
+            label={`Color at ${width}`}
+            onChange={() => {}}
+            presets={PRESETS}
+            value="#F9A8D4"
+          />
+        </Field>
+      )}
+    </ContainerBoard>
+  ),
+}