@varialkit/colorpicker 0.1.0

package/docs.md

@@ -0,0 +1,124 @@
+# ColorPicker
+
+The ColorPicker combines user-defined presets, a format-aware value editor, and optional advanced controls for hue,
+opacity, and freeform spectrum selection. The content (`ColorPickerContent`) can be used inline or embedded inside
+another surface, while the wrapper (`ColorPicker`) handles the menu trigger. The palette (`ColorPickerPalette`) and
+swatch (`ColorPickerSwatch`) are independent so the preset grid can be embedded in menus, popovers, or custom
+surfaces.
+
+## Exports
+
+- `ColorPicker`
+- `ColorPickerContent`
+- `ColorPickerPalette`
+- `ColorPickerSwatch`
+- `ColorPreview`
+
+## How It Works
+
+The ColorPicker package is intentionally split into small building blocks so you can assemble a color selection
+experience that fits the surface you are working with (menu, popover, inline panel, etc.).
+
+**Composition flow**
+
+1. `ColorPicker` is the wrapper that wires a trigger to a dropdown `Menu`.
+2. Inside the menu, it renders `ColorPickerContent` to handle advanced controls + presets + value input.
+3. `ColorPickerContent` renders the optional spectrum / sliders / eyedropper row, the optional value editor row, and
+   a `ColorPickerPalette` for presets.
+4. `ColorPickerPalette` renders a grid of `ColorPickerSwatch` instances.
+5. `ColorPreview` is a separate, reusable indicator for the currently selected color and can be used as a trigger.
+
+**Data flow**
+
+- `value` can be `hex`, `rgba`, or `hsla`; the picker normalizes it into an internal HSVA model so presets, sliders,
+  opacity, and typed values stay in sync.
+- `onChange` fires when a preset, spectrum, slider, eyedropper, or valid typed value updates the selection.
+- `onSelectColor` still fires for preset selections only (useful when you want to differentiate menu-click events).
+- `presets` is the preferred way to provide user-controlled menu colors. `colors` remains supported as a legacy alias.
+- `presets` / `colors` can be an array of strings or structured palette entries. Structured entries allow per-swatch
+  labels, overlay content, and disabled state.
+- `valueFormat` controls what `onChange` emits (`hex`, `rgba`, or `hsla`).
+- `defaultInputFormat`, `inputFormats`, and `showFormatSelector` control the value editor row.
+- `menuWidth` and `menuHeight` let the wrapper size the dropdown for larger editing surfaces.
+- `swatchRadius` and `swatchContent` let you tune the swatch shape and overlay without replacing the palette
+  component.
+
+**Menu behavior**
+
+- `ColorPicker` uses `MenuDropdown` and disables auto-close so the content can handle selection.
+- `closeOnSelect` enables closing the dropdown after a swatch is clicked while keeping hex input changes inline.
+
+## Subcomponents
+
+**`ColorPicker`**
+
+Use this when you want a trigger + dropdown. It provides the default `ColorPreview` trigger and passes through
+menu placement props. It also owns the open state (controlled or uncontrolled).
+
+**`ColorPickerContent`**
+
+Use this when you want to render the picker inline inside another surface (menu, popover, panel). It handles
+value normalization, preset selection, optional advanced controls, and optional typed value editing.
+
+**`ColorPickerPalette`**
+
+Renders the grid of swatches. It is fully independent and can be used directly. The `colors` prop supports:
+
+- Hex strings: `["#ef4444", "#22c55e"]`
+- Objects: `{ value, label, content, disabled }`
+
+When you need overlay content or a different radius for all swatches, prefer `swatchContent` and `swatchRadius`
+instead of re-implementing the grid.
+
+## Advanced Controls
+
+`ColorPickerContent` stays palette-first by default, but you can opt into richer menu controls:
+
+- `showSpectrum`: adds the full-width saturation / brightness field.
+- `showHueSlider`: adds the horizontal hue slider.
+- `showOpacitySlider`: adds the horizontal opacity slider.
+- `showEyedropper`: adds the native `EyeDropper` button when supported by the browser.
+- `showValueInput`: shows the typed value editor row. `showHexInput` still works as a legacy alias.
+- `showFormatSelector`: adds the value-type dropdown (`hex`, `rgba`, `hsla` by default).
+- `showOpacityInput`: adds the alpha / opacity text field on the right side of the value row.
+
+These controls render above the presets so you can progressively enhance the menu without replacing the existing swatch
+grid behavior.
+
+When the preset list is long, the preset section becomes scrollable so the advanced controls and typed input stay
+visible.
+
+## Presets
+
+Treat the swatch grid as a preset section controlled by the component consumer:
+
+```tsx
+<ColorPicker
+  value={color}
+  onChange={setColor}
+  presets={[
+    { value: "#FF4D4F", label: "Error" },
+    { value: "#1677FF", label: "Primary" },
+    { value: "#111827", label: "Ink" },
+  ]}
+/>
+```
+
+`colors` still works, but new usage should prefer `presets` because it better reflects that these entries are
+consumer-defined menu content.
+
+**`ColorPickerSwatch`**
+
+The individual cell used by the palette. This is useful when you want to build a custom grid or layout while
+preserving the built-in focus/selection styles. It accepts `radius`, `size`, and optional overlay `children`.
+
+**`ColorPreview`**
+
+A small, reusable color indicator. It can be used as a trigger or a static label in forms, tables, or lists.
+
+## Notes
+
+- `ColorPicker` uses `MenuDropdown` and disables menu auto-close so advanced controls and typed input can stay inline.
+- Use `ColorPreview` on its own when you only need a swatch indicator.
+- `ColorPickerPalette` accepts `colors` as either strings or objects with `{ value, label, content, disabled }`.
+- Use `swatchRadius` and `swatchContent` (or `ColorPickerSwatch`) when you need custom corner rounding or overlay content.

package/examples.tsx

@@ -0,0 +1,376 @@
+import React, { useState } from "react";
+import { ColorPicker, ColorPickerContent, ColorPickerPalette, ColorPickerSwatch, ColorPreview } from "./src";
+import { Menu } from "@solara/menu";
+
+export const stories = {
+  triggered: {
+    title: "Triggered picker",
+    description: "A menu-triggered color picker using the default preview trigger.",
+    showProps: false,
+    render: () => <TriggeredExample />,
+    code: `import React from "react";
+import { ColorPicker } from "@solara/colorpicker";
+
+export function Example() {
+  const [color, setColor] = React.useState("#3b82f6");
+  return <ColorPicker value={color} onChange={setColor} />;
+}
+`,
+  },
+  advancedMenu: {
+    title: "Advanced menu controls",
+    description: "Opt into spectrum, hue, opacity, eyedropper, and format-aware value editing above presets.",
+    showProps: false,
+    render: () => <AdvancedMenuExample />,
+    code: `import React from "react";
+import { ColorPicker } from "@solara/colorpicker";
+
+export function Example() {
+  const [color, setColor] = React.useState("#C94B4B");
+
+  return (
+    <ColorPicker
+      value={color}
+      onChange={setColor}
+      menuWidth={340}
+      menuHeight={520}
+      presets={[
+        { value: "#C94B4B", label: "Brand red" },
+        { value: "#E35D5B", label: "Rose clay" },
+        { value: "#F97316", label: "Orange" },
+        { value: "#FB923C", label: "Apricot" },
+        { value: "#EAB308", label: "Gold" },
+        { value: "#FACC15", label: "Sun" },
+        { value: "#22C55E", label: "Green" },
+        { value: "#4ADE80", label: "Mint" },
+        { value: "#14B8A6", label: "Teal" },
+        { value: "#06B6D4", label: "Cyan" },
+        { value: "#3B82F6", label: "Blue" },
+        { value: "#6366F1", label: "Indigo" },
+        { value: "#8B5CF6", label: "Violet" },
+        { value: "#A855F7", label: "Purple" },
+        { value: "#EC4899", label: "Pink" },
+        { value: "#F43F5E", label: "Crimson" },
+        { value: "#6B7280", label: "Slate" },
+        { value: "#111827", label: "Ink" },
+        { value: "#000000", label: "Black" },
+        { value: "#FFFFFF", label: "White" },
+      ]}
+      showSpectrum
+      showHueSlider
+      showOpacitySlider
+      showEyedropper
+      showFormatSelector
+      showOpacityInput
+      valueFormat="rgba"
+      triggerLabel="Brand color"
+    />
+  );
+}
+`,
+  },
+  customPalette: {
+    title: "Custom palette",
+    description: "Supply a custom preset section and hide the value input row.",
+    showProps: false,
+    render: () => <CustomPaletteExample />,
+    code: `import React from "react";
+import { ColorPicker } from "@solara/colorpicker";
+
+export function Example() {
+  const [color, setColor] = React.useState("#ff6b6b");
+
+  return (
+    <ColorPicker
+      value={color}
+      onChange={setColor}
+      colors={["#ff6b6b", "#4ecdc4", "#45b7d1", "#96ceb4", "#ffeaa7", "#dda0dd"]}
+      showHexInput={false}
+      triggerLabel="Accent"
+    />
+  );
+}
+`,
+  },
+  inline: {
+    title: "Inline content",
+    description: "Use ColorPickerContent directly inside a surface.",
+    showProps: false,
+    render: () => <InlineExample />,
+    code: `import React from "react";
+import { ColorPickerContent } from "@solara/colorpicker";
+import { Menu } from "@solara/menu";
+
+export function Example() {
+  const [color, setColor] = React.useState("#22c55e");
+
+  return (
+    <Menu style={{ width: 280 }}>
+      <ColorPickerContent value={color} onChange={setColor} />
+    </Menu>
+  );
+}
+`,
+  },
+  preview: {
+    title: "ColorPreview",
+    description: "The preview component can be used as a standalone swatch.",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+        <ColorPreview color="#ef4444" size="lg" label="Primary" />
+        <ColorPreview color="#000000" size="lg" shape="circle" label="Ink" />
+      </div>
+    ),
+    code: `import { ColorPreview } from "@solara/colorpicker";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <ColorPreview color="#ef4444" size="lg" label="Primary" />
+      <ColorPreview color="#000000" size="lg" shape="circle" label="Ink" />
+    </div>
+  );
+}
+`,
+  },
+  previewVariants: {
+    title: "ColorPreview variants",
+    description: "Label vs no label, plus size and radius adjustments.",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", gap: 16, alignItems: "center", flexWrap: "wrap" }}>
+        <ColorPreview color="#3b82f6" size="sm" label="Small" />
+        <ColorPreview color="#22c55e" size="md" label="Medium" />
+        <ColorPreview color="#f59e0b" size="lg" label="Large" />
+        <ColorPreview color="#111827" size="md" />
+        <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
+          <ColorPreview
+            color="#ec4899"
+            size="md"
+            label="Rounded"
+            style={{ ["--colorpreview-swatch-size" as const]: "32px" } as React.CSSProperties}
+          />
+          <span
+            style={{
+              width: 28,
+              height: 28,
+              borderRadius: 999,
+              background: "#ec4899",
+              boxShadow: "inset 0 0 2px rgba(0,0,0,0.4)",
+            }}
+          />
+        </div>
+      </div>
+    ),
+    code: `import { ColorPreview } from "@solara/colorpicker";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: 16, alignItems: "center", flexWrap: "wrap" }}>
+      <ColorPreview color="#3b82f6" size="sm" label="Small" />
+      <ColorPreview color="#22c55e" size="md" label="Medium" />
+      <ColorPreview color="#f59e0b" size="lg" label="Large" />
+      <ColorPreview color="#111827" size="md" />
+      <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
+        <ColorPreview
+          color="#ec4899"
+          size="md"
+          label="Rounded"
+          style={{ ["--colorpreview-swatch-size" as const]: "32px" }}
+        />
+        <span
+          style={{
+            width: 28,
+            height: 28,
+            borderRadius: 999,
+            background: "#ec4899",
+            boxShadow: "inset 0 0 2px rgba(0,0,0,0.4)",
+          }}
+        />
+      </div>
+    </div>
+  );
+}
+`,
+  },
+  paletteSwatches: {
+    title: "Palette swatches",
+    description: "Use swatches directly with custom radius and overlay content.",
+    showProps: false,
+    render: () => (
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(6, 1fr)",
+          gap: 8,
+          padding: 12,
+          background: "var(--color-surface-100)",
+          borderRadius: 8,
+        }}>
+        {["#ef4444", "#f59e0b", "#22c55e", "#3b82f6", "#6366f1", "#ec4899"].map(
+          (color) => (
+            <ColorPickerSwatch
+              key={color}
+              color={color}
+              size="md"
+              radius="12px"
+              aria-label={`Swatch ${color}`}
+            />
+          )
+        )}
+        <ColorPickerSwatch color="#111827" size="md" radius="6px">
+          A
+        </ColorPickerSwatch>
+        <ColorPickerSwatch color="#000000" size="md" radius="4px">
+          B
+        </ColorPickerSwatch>
+      </div>
+    ),
+    code: `import { ColorPickerSwatch } from "@solara/colorpicker";
+
+export function Example() {
+  return (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns: "repeat(6, 1fr)",
+        gap: 8,
+        padding: 12,
+        background: "var(--color-surface-100)",
+        borderRadius: 8,
+      }}
+    >
+      {["#ef4444", "#f59e0b", "#22c55e", "#3b82f6", "#6366f1", "#ec4899"].map(
+        (color) => (
+          <ColorPickerSwatch
+            key={color}
+            color={color}
+            size="md"
+            radius="12px"
+            aria-label={\`Swatch \${color}\`}
+          />
+        )
+      )}
+      <ColorPickerSwatch color="#111827" size="md" radius="6px">
+        A
+      </ColorPickerSwatch>
+      <ColorPickerSwatch color="#000000" size="md" radius="4px">
+        B
+      </ColorPickerSwatch>
+    </div>
+  );
+}
+`,
+  },
+  paletteComponent: {
+    title: "ColorPickerPalette",
+    description: "Palette component with per-swatch content and radius overrides.",
+    showProps: false,
+    render: () => (
+      <ColorPickerPalette
+        value="#3b82f6"
+        size="sm"
+        swatchRadius="10px"
+        colors={[
+          { value: "#ef4444", label: "Red", content: "R" },
+          { value: "#f59e0b", label: "Amber", content: "A" },
+          { value: "#22c55e", label: "Green", content: "G" },
+          { value: "#3b82f6", label: "Blue", content: "B" },
+          { value: "#6366f1", label: "Indigo", content: "I" },
+          { value: "#ec4899", label: "Pink", content: "P" },
+        ]}
+      />
+    ),
+    code: `import { ColorPickerPalette } from "@solara/colorpicker";
+
+export function Example() {
+  return (
+    <ColorPickerPalette
+      value="#3b82f6"
+      size="sm"
+      swatchRadius="10px"
+      colors={[
+        { value: "#ef4444", label: "Red", content: "R" },
+        { value: "#f59e0b", label: "Amber", content: "A" },
+        { value: "#22c55e", label: "Green", content: "G" },
+        { value: "#3b82f6", label: "Blue", content: "B" },
+        { value: "#6366f1", label: "Indigo", content: "I" },
+        { value: "#ec4899", label: "Pink", content: "P" },
+      ]}
+    />
+  );
+}
+`,
+  },
+};
+
+function TriggeredExample() {
+  const [color, setColor] = useState("#3b82f6");
+  return <ColorPicker value={color} onChange={setColor} />;
+}
+
+function AdvancedMenuExample() {
+  const [color, setColor] = useState("#C94B4B");
+
+  return (
+    <ColorPicker
+      value={color}
+      onChange={setColor}
+      menuWidth={340}
+      menuHeight={520}
+      presets={[
+        { value: "#C94B4B", label: "Brand red" },
+        { value: "#E35D5B", label: "Rose clay" },
+        { value: "#F97316", label: "Orange" },
+        { value: "#FB923C", label: "Apricot" },
+        { value: "#EAB308", label: "Gold" },
+        { value: "#FACC15", label: "Sun" },
+        { value: "#22C55E", label: "Green" },
+        { value: "#4ADE80", label: "Mint" },
+        { value: "#14B8A6", label: "Teal" },
+        { value: "#06B6D4", label: "Cyan" },
+        { value: "#3B82F6", label: "Blue" },
+        { value: "#6366F1", label: "Indigo" },
+        { value: "#8B5CF6", label: "Violet" },
+        { value: "#A855F7", label: "Purple" },
+        { value: "#EC4899", label: "Pink" },
+        { value: "#F43F5E", label: "Crimson" },
+        { value: "#6B7280", label: "Slate" },
+        { value: "#111827", label: "Ink" },
+        { value: "#000000", label: "Black" },
+        { value: "#FFFFFF", label: "White" },
+      ]}
+      showSpectrum
+      showHueSlider
+      showOpacitySlider
+      showEyedropper
+      showFormatSelector
+      showOpacityInput
+      valueFormat="rgba"
+      triggerLabel="Brand color"
+    />
+  );
+}
+
+function CustomPaletteExample() {
+  const [color, setColor] = useState("#ff6b6b");
+  return (
+    <ColorPicker
+      value={color}
+      onChange={setColor}
+      presets={["#ff6b6b", "#4ecdc4", "#45b7d1", "#96ceb4", "#ffeaa7", "#dda0dd"]}
+      showValueInput={false}
+      triggerLabel="Accent"
+    />
+  );
+}
+
+function InlineExample() {
+  const [color, setColor] = useState("#22c55e");
+  return (
+    <Menu style={{ width: 280 }}>
+      <ColorPickerContent value={color} onChange={setColor} />
+    </Menu>
+  );
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@varialkit/colorpicker",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples.tsx"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "dependencies": {
+    "@varialkit/textfield": "0.1.0",
+    "@varialkit/menu": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}