@charcuterie/ui 4.26.2 → 4.27.0

package/src/ColorPicker/ColorPicker.tsx

@@ -0,0 +1,347 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+import { useRef, useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Combobox } from "../Combobox/Combobox.tsx"
+import type { ListboxItem } from "../Listbox/Listbox.tsx"
+import { Swatch } from "../Swatch/Swatch.tsx"
+import { toClassName } from "../toClassName.ts"
+import { ColorPickerCustomPanel } from "./ColorPickerCustomPanel.tsx"
+import { parseHexColor } from "./parseHexColor.ts"
+
+export type ColorPreset = {
+  /**
+   * Other words that find it — the family a name does not say. "Blush"
+   * and "Cotton Candy" are pinks, and a person types "pink".
+   */
+  keywords?: readonly string[]
+  /** What a person reads and types to find it — "Hot Pink", not "Pink 3". */
+  name: string
+  /** A `#RRGGBB` color. */
+  value: string
+}
+
+/**
+ * The value the "Custom color…" row carries. It cannot collide with a
+ * preset, because every preset value starts with `#`.
+ */
+const CUSTOM_OPTION_VALUE = "custom-color"
+
+/** See `Picker` — a constant element, so the file holds one component. */
+const CHEVRON_DOWN = (
+  <svg
+    aria-hidden="true"
+    className="size-4"
+    fill="none"
+    focusable={false}
+    stroke="currentColor"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    strokeWidth={1.75}
+    viewBox="0 0 24 24"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path d="m6 9 6 6 6-6" />
+  </svg>
+)
+
+export type ColorPickerProps = Omit<
+  ComponentPropsWithRef<"button">,
+  "color" | "disabled" | "onChange" | "value"
+> & {
+  /**
+   * Shown under a custom draft when the app refuses it, and the reason
+   * **Use color** stays disabled. Answer `null` to accept. It is asked
+   * of custom colors only: the presets are the app's own list, so it
+   * already vetted them.
+   */
+  getColorError?: (hex: string) => null | string
+  /** Adds the "Custom color…" row and the custom panel it opens. */
+  isCustomAllowed?: boolean
+  isDisabled?: boolean
+  /** What the color is FOR — "Second's color". Not the current value. */
+  label: string
+  /**
+   * A preset answers its own `value`, as written. A custom color
+   * answers `#RRGGBB` in upper case.
+   */
+  onChange: (hex: string) => void
+  /** Read by the trigger when there is no value yet. */
+  placeholder?: string
+  presets: readonly ColorPreset[]
+  /** The search field's hint. */
+  searchPlaceholder?: string
+  size?: ControlSize
+  value?: string
+}
+
+const isSameColor = (first: string, second: string) =>
+  (parseHexColor(first) ?? first) ===
+  (parseHexColor(second) ?? second)
+
+/**
+ * A named color from a list, or a color of the person's own.
+ *
+ * ### Presets are a `Combobox`, because a palette worth offering is long
+ *
+ * Two dozen colors in a swatch grid is a wall of dots; the same list
+ * as rows with a name lets a person type "pink" and see only the
+ * pinks. Each row is a `Swatch` and its name; the name and the
+ * preset's `keywords` are the search target, so "Blush" can answer
+ * "pink". A hex code finds its preset too.
+ *
+ * ### Custom is a mode, not the whole control
+ *
+ * `isCustomAllowed` adds a last row, "Custom color…", which is always
+ * listed whatever the search says. Choosing it reveals
+ * `ColorPickerCustomPanel` under the trigger: the browser's color
+ * wheel and a hex field, applied only on **Use color**. Typing a hex
+ * code into the search and choosing the custom row opens the panel on
+ * that code.
+ *
+ * ### The app decides what a custom color may be
+ *
+ * `getColorError` is the app's rule — a reader board that cannot show
+ * gray, a label that has to clear contrast on both schemes. The
+ * component does not know why a color is wrong, only that it is, and
+ * it shows the app's sentence.
+ *
+ * ### The trigger says the name, or the code
+ *
+ * A preset reads `"Color: Hot Pink"`; a custom color reads
+ * `"Color: #FF3399"`, because a custom color has no name and its code
+ * is what is on screen (WCAG 2.5.3, as `Picker` argues).
+ */
+export const ColorPicker = ({
+  className,
+  getColorError,
+  isCustomAllowed = false,
+  isDisabled = false,
+  label,
+  onChange,
+  placeholder = "Choose a color",
+  presets,
+  searchPlaceholder = "Search colors…",
+  size = "md",
+  value,
+  ...buttonProps
+}: ColorPickerProps): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility()
+
+  const [query, setQuery] = useState("")
+
+  /**
+   * The color the custom panel opens on, or `null` while it is closed.
+   * Held here rather than inside the panel so a reopen starts fresh.
+   */
+  const [customSeed, setCustomSeed] = useState<
+    null | string
+  >(null)
+
+  const triggerElement = useRef<HTMLButtonElement>(null)
+
+  const currentPreset =
+    value === undefined
+      ? undefined
+      : presets.find((preset) =>
+          isSameColor(preset.value, value),
+        )
+
+  const customValue =
+    value === undefined || currentPreset !== undefined
+      ? null
+      : (parseHexColor(value) ?? value)
+
+  const triggerText =
+    currentPreset?.name ?? customValue ?? placeholder
+
+  const swatchColor = currentPreset?.value ?? customValue
+
+  const normalizedQuery = query.trim().toLowerCase()
+
+  const queryDigits = normalizedQuery.replace(/^#/, "")
+
+  const matchingPresets =
+    normalizedQuery === ""
+      ? presets
+      : presets.filter(
+          (preset) =>
+            [preset.name, ...(preset.keywords ?? [])].some(
+              (word) =>
+                word
+                  .toLowerCase()
+                  .includes(normalizedQuery),
+            ) ||
+            (queryDigits.length > 0 &&
+              preset.value
+                .toLowerCase()
+                .replace(/^#/, "")
+                .startsWith(queryDigits)),
+        )
+
+  const queryColor = parseHexColor(query)
+
+  const customOptionText =
+    queryColor === null
+      ? "Custom color…"
+      : `Custom color ${queryColor}…`
+
+  const options: ListboxItem[] = [
+    ...matchingPresets.map((preset) => ({
+      label: (
+        <span className="flex items-center gap-2">
+          {/* Hidden: the row's text already names it, and a named
+              image beside it would read "Hot Pink Hot Pink". */}
+          <span aria-hidden="true" className="inline-flex">
+            <Swatch
+              color={preset.value}
+              label={preset.name}
+              size="sm"
+            />
+          </span>
+          <span>{preset.name}</span>
+        </span>
+      ),
+      textValue: preset.name,
+      value: preset.value,
+    })),
+    ...(isCustomAllowed
+      ? [
+          {
+            label: (
+              <span className="flex items-center gap-2">
+                {queryColor === null ? null : (
+                  <span
+                    aria-hidden="true"
+                    className="inline-flex"
+                  >
+                    <Swatch
+                      color={queryColor}
+                      label={queryColor}
+                      size="sm"
+                    />
+                  </span>
+                )}
+                <span>{customOptionText}</span>
+              </span>
+            ),
+            textValue: customOptionText,
+            value: CUSTOM_OPTION_VALUE,
+          },
+        ]
+      : []),
+  ]
+
+  const selectedValue =
+    currentPreset?.value ??
+    (customValue === null ? undefined : CUSTOM_OPTION_VALUE)
+
+  const dismiss = () => {
+    setQuery("")
+
+    hide()
+  }
+
+  const closeCustomPanel = () => {
+    setCustomSeed(null)
+
+    triggerElement.current?.focus()
+  }
+
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <Combobox
+        emptyLabel="No color by that name"
+        isVisible={isVisible && !isDisabled}
+        itemSize={size}
+        // The selection is read off `value` on each open. Combobox seeds
+        // its tick once, so a value that moved under it — a custom color
+        // applied from the panel — remounts it rather than leaving the
+        // old preset ticked.
+        key={`combobox-${selectedValue ?? "none"}`}
+        onDismiss={dismiss}
+        onQueryChange={setQuery}
+        onSelect={(optionValue) => {
+          if (optionValue === CUSTOM_OPTION_VALUE) {
+            setCustomSeed(
+              queryColor ??
+                customValue ??
+                currentPreset?.value ??
+                presets[0]?.value ??
+                "",
+            )
+          } else {
+            setCustomSeed(null)
+
+            onChange(optionValue)
+          }
+
+          setQuery("")
+        }}
+        options={options}
+        placeholder={searchPlaceholder}
+        query={query}
+        selectedValue={selectedValue}
+        trigger={
+          <Button
+            {...buttonProps}
+            appearance="outline"
+            aria-label={`${label}: ${triggerText}`}
+            className={toClassName(
+              "justify-between",
+              className,
+            )}
+            iconEnd={CHEVRON_DOWN}
+            intent="neutral"
+            isDisabled={isDisabled}
+            onClick={(clickEvent) => {
+              buttonProps.onClick?.(clickEvent)
+
+              toggle()
+            }}
+            ref={triggerElement}
+            size={size}
+            type="button"
+          >
+            <span className="-mx-1 flex min-w-0 grow items-center gap-2 overflow-x-clip px-1 text-start">
+              {swatchColor === null ||
+              swatchColor === undefined ? null : (
+                <Swatch
+                  color={swatchColor}
+                  label={triggerText}
+                  size="sm"
+                />
+              )}
+              <span className="min-w-0 truncate">
+                {triggerText}
+              </span>
+            </span>
+          </Button>
+        }
+      />
+
+      {customSeed === null ? null : (
+        <ColorPickerCustomPanel
+          getColorError={getColorError}
+          initialColor={customSeed}
+          isDisabled={isDisabled}
+          // A new seed is a new draft.
+          key={`custom-${customSeed}`}
+          label={label}
+          onApply={(hex) => {
+            onChange(hex)
+
+            closeCustomPanel()
+          }}
+          onCancel={closeCustomPanel}
+          size={size}
+        />
+      )}
+    </div>
+  )
+}

package/src/ColorPicker/ColorPickerCustomPanel.tsx

@@ -0,0 +1,224 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useEffect, useRef, useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { CONTROL_SIZE_CLASS } from "../controlStyles.ts"
+import { Field } from "../Field/Field.tsx"
+import {
+  DISABLED_CLASS,
+  FOCUS_RING_CLASS,
+} from "../intentStyles.ts"
+import { Swatch } from "../Swatch/Swatch.tsx"
+import { toClassName } from "../toClassName.ts"
+import { parseHexColor } from "./parseHexColor.ts"
+
+const TEXT_INPUT_CLASS =
+  "w-full min-w-0 rounded-md border border-border-default bg-surface-raised font-mono text-content-primary transition-colors duration-(--duration-fast) ease-standard placeholder:text-content-muted hover:border-border-strong aria-invalid:border-intent-danger-border"
+
+/**
+ * The browser's own swatch button. Its inner padding and the
+ * `::-webkit-color-swatch` border are what make the stock control look
+ * like a grey box with a colored stamp in it; zeroing both leaves a
+ * flat chip the height of the field beside it.
+ */
+const NATIVE_COLOR_INPUT_CLASS =
+  "h-(--control-height-md) w-16 shrink-0 cursor-pointer rounded-md border border-border-default bg-surface-raised p-1 hover:border-border-strong [&::-moz-color-swatch]:rounded-sm [&::-moz-color-swatch]:border-0 [&::-webkit-color-swatch-wrapper]:p-0 [&::-webkit-color-swatch]:rounded-sm [&::-webkit-color-swatch]:border-0"
+
+export type ColorPickerCustomPanelProps = {
+  /** The color the panel opens on — the current custom value, or a seed. */
+  initialColor: string
+  isDisabled: boolean
+  label: string
+  onApply: (hex: string) => void
+  onCancel: () => void
+  getColorError?: (hex: string) => null | string
+  size: ControlSize
+}
+
+/**
+ * The custom-color surface `ColorPicker` reveals under its trigger.
+ *
+ * ### The native color input is allowed here, and only here
+ *
+ * Every other picker in this library is ours because the OS paints the
+ * native one and no token reaches inside it. A custom color is the one
+ * case where the OS dialog is the right tool: it has the wheel, the
+ * eyedropper and the sliders, none of which a person wants rebuilt.
+ * So the native `<input type="color">` is the custom MODE, inside a
+ * panel this component owns — never the whole picker, which is the
+ * shape the presets replace.
+ *
+ * ### Nothing is applied until the person says so
+ *
+ * The native input fires on every movement of the wheel. Applying each
+ * one would write dozens of colors to an app's server while a person
+ * drags, and a refused color would flash an error mid-drag. The panel
+ * holds a draft; **Use color** applies it, Enter in the hex field does
+ * the same, and Escape or **Cancel** drops it.
+ */
+export const ColorPickerCustomPanel = ({
+  getColorError,
+  initialColor,
+  isDisabled,
+  label,
+  onApply,
+  onCancel,
+  size,
+}: ColorPickerCustomPanelProps): ReactNode => {
+  const [draftText, setDraftText] = useState(initialColor)
+
+  const [lastValidColor, setLastValidColor] = useState(
+    parseHexColor(initialColor) ?? "",
+  )
+
+  const hexInputElement = useRef<HTMLInputElement>(null)
+
+  // A frame late on purpose. The panel opens from a `Combobox` row, and
+  // closing that popup hands focus back to the trigger after this
+  // effect has run; focusing now would be undone a moment later.
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => {
+      hexInputElement.current?.focus()
+      hexInputElement.current?.select()
+    })
+
+    return () => {
+      cancelAnimationFrame(frame)
+    }
+  }, [])
+
+  const draftColor = parseHexColor(draftText)
+
+  const error =
+    draftColor === null
+      ? draftText.trim() === ""
+        ? undefined
+        : "Enter three or six hex digits, such as 3A86FF."
+      : (getColorError?.(draftColor) ?? undefined)
+
+  const isApplicable =
+    !isDisabled &&
+    draftColor !== null &&
+    error === undefined
+
+  const apply = () => {
+    if (isApplicable) {
+      onApply(draftColor)
+    }
+  }
+
+  const updateDraft = (text: string) => {
+    setDraftText(text)
+
+    const parsed = parseHexColor(text)
+
+    if (parsed !== null) {
+      setLastValidColor(parsed)
+    }
+  }
+
+  return (
+    <fieldset
+      aria-label={`${label}: custom color`}
+      className="flex min-w-0 flex-col gap-3 rounded-md border border-border-subtle bg-surface-raised p-3"
+      onKeyDown={(keyEvent) => {
+        if (keyEvent.key === "Escape") {
+          keyEvent.preventDefault()
+          keyEvent.stopPropagation()
+
+          onCancel()
+        }
+      }}
+    >
+      <div className="flex flex-wrap items-start gap-3">
+        <Field label="Color wheel">
+          <input
+            aria-label={`${label}: color wheel`}
+            className={toClassName(
+              NATIVE_COLOR_INPUT_CLASS,
+              FOCUS_RING_CLASS,
+              DISABLED_CLASS,
+            )}
+            disabled={isDisabled}
+            onChange={(changeEvent) => {
+              updateDraft(
+                changeEvent.currentTarget.value.toUpperCase(),
+              )
+            }}
+            type="color"
+            value={(
+              draftColor ?? lastValidColor
+            ).toLowerCase()}
+          />
+        </Field>
+
+        <Field
+          className="min-w-40 flex-1"
+          error={error}
+          label="Hex code"
+        >
+          <input
+            autoComplete="off"
+            className={toClassName(
+              TEXT_INPUT_CLASS,
+              CONTROL_SIZE_CLASS[size],
+              FOCUS_RING_CLASS,
+              DISABLED_CLASS,
+            )}
+            disabled={isDisabled}
+            onChange={(changeEvent) => {
+              updateDraft(changeEvent.currentTarget.value)
+            }}
+            onKeyDown={(keyEvent) => {
+              if (keyEvent.key === "Enter") {
+                keyEvent.preventDefault()
+
+                apply()
+              }
+            }}
+            placeholder="RRGGBB"
+            ref={hexInputElement}
+            spellCheck={false}
+            type="text"
+            value={draftText}
+          />
+        </Field>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-2">
+        {draftColor === null ? null : (
+          <Swatch
+            className="me-auto"
+            color={draftColor}
+            isLabelVisible
+            label={draftColor}
+            size="sm"
+          />
+        )}
+
+        <Button
+          appearance="ghost"
+          intent="neutral"
+          isDisabled={isDisabled}
+          onClick={onCancel}
+          size={size}
+          type="button"
+        >
+          Cancel
+        </Button>
+
+        <Button
+          appearance="solid"
+          intent="accent"
+          isDisabled={!isApplicable}
+          onClick={apply}
+          size={size}
+          type="button"
+        >
+          Use color
+        </Button>
+      </div>
+    </fieldset>
+  )
+}

package/src/ColorPicker/parseHexColor.ts

@@ -0,0 +1,37 @@
+const SHORT_HEX_PATTERN = /^[0-9a-f]{3}$/i
+
+const LONG_HEX_PATTERN = /^[0-9a-f]{6}$/i
+
+/**
+ * Reads what a person types into a hex field — `3a86ff`, `#3A86FF`,
+ * `#38f`, with or without the leading mark and with stray spaces — and
+ * answers the one canonical form, `#RRGGBB` in upper case, or `null`
+ * when it is not a color.
+ *
+ * Upper case because that is how the fleet's palettes are written and
+ * how a person reads a code aloud; a native `<input type="color">`
+ * answers lower case, and two spellings of one color are how a
+ * "is this the preset?" comparison quietly fails.
+ *
+ * No alpha. A child's color, a label's color, a sticker's color is
+ * opaque, and an eight-digit code would let a translucent value
+ * through every contrast rule an app writes against it.
+ */
+export const parseHexColor = (
+  text: string,
+): string | null => {
+  const digits = text.trim().replace(/^#/, "")
+
+  if (SHORT_HEX_PATTERN.test(digits)) {
+    return `#${[...digits]
+      .map((digit) => `${digit}${digit}`)
+      .join("")
+      .toUpperCase()}`
+  }
+
+  if (LONG_HEX_PATTERN.test(digits)) {
+    return `#${digits.toUpperCase()}`
+  }
+
+  return null
+}

package/src/index.ts

@@ -121,6 +121,12 @@ export type { ChartProps } from "./Chart/Chart.tsx"
 export { Chart } from "./Chart/Chart.tsx"
 export type { CheckboxProps } from "./Checkbox/Checkbox.tsx"
 export { Checkbox } from "./Checkbox/Checkbox.tsx"
+export type {
+  ColorPickerProps,
+  ColorPreset,
+} from "./ColorPicker/ColorPicker.tsx"
+export { ColorPicker } from "./ColorPicker/ColorPicker.tsx"
+export { parseHexColor } from "./ColorPicker/parseHexColor.ts"
 export type { ColorSchemeSwitcherProps } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
 export { ColorSchemeSwitcher } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
 export type {

package/src/sourceRules.test.ts

@@ -627,7 +627,9 @@ test("the barrel is the only place components are re-exported", async () => {
   // and whereabouts each drew it by hand. `GroupedListRow.tsx` is its
   // member and stays out of this count by the `<Name>/<Name>.tsx` rule.
   // CommandPalette composes Modal and SearchInput into the launcher.
-  expect(componentNames.length).toBe(79)
+  // ColorPicker composes Combobox and Swatch with a custom-color panel;
+  // `ColorPickerCustomPanel.tsx` is its member.
+  expect(componentNames.length).toBe(80)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)