@forte-ui/react 1.0.0-alpha.1

package/dist/components/color-picker/ColorPicker.d.ts

@@ -0,0 +1,553 @@
+import { Popover, PopoverPopupProps } from '../popover';
+import { DEFAULT_SWATCHES, ColorPickerFormat, Hsva, Rgba } from './color';
+import * as React from "react";
+export type { ColorPickerFormat, Hsva, Rgba };
+export { DEFAULT_SWATCHES };
+/** What moved the colour. Handed to `onValueChange` and `onValueCommitted` so
+ * a consumer can tell a drag from a paste without watching the DOM. */
+export type ColorPickerChangeReason = "area" | "hue" | "alpha" | "swatch" | "input" | "eye-dropper" | "format-change" | "none";
+export interface ColorPickerChangeDetails {
+    /** The colour in the picker's internal model — hue survives here at zero
+     * saturation, where the string cannot carry it. */
+    hsva: Hsva;
+    /** The same colour as eight-bit sRGB, so a consumer never has to re-parse
+     * the string it was just handed. */
+    rgba: Rgba;
+    /** The notation `value` is written in. */
+    format: ColorPickerFormat;
+    /** What moved it. */
+    reason: ColorPickerChangeReason;
+}
+type PopoverRootProps = React.ComponentProps<typeof Popover.Root>;
+export interface ColorPickerRootProps {
+    /**
+     * The selected colour, as a CSS colour string. Pass it with
+     * `onValueChange` to control the picker.
+     *
+     * Accepts `#hex` (3, 4, 6 or 8 digits), `rgb()`, `hsl()`, `oklch()`,
+     * `oklab()` and `transparent`, in both the legacy comma form and the modern
+     * space form. A string that cannot be read is ignored rather than throwing,
+     * so a half-typed value in your own state never blanks the picker. Named
+     * colours (`rebeccapurple`) are not accepted — see the docs page.
+     */
+    value?: string;
+    /**
+     * The colour the picker starts on when it is uncontrolled.
+     * @default "#000000"
+     */
+    defaultValue?: string;
+    /**
+     * Called on every change, including each frame of a drag. `value` is
+     * written in the current `format`; `details` carries the same colour as
+     * HSVA and RGBA, plus what moved it.
+     */
+    onValueChange?: (value: string, details: ColorPickerChangeDetails) => void;
+    /**
+     * Called when an interaction ENDS — pointer up, a keyboard step, a swatch
+     * press, a committed text entry. This is the one to persist from: a drag
+     * across the area fires `onValueChange` once per pointer move and this once.
+     */
+    onValueCommitted?: (value: string, details: ColorPickerChangeDetails) => void;
+    /**
+     * Which notation `value` is written in. Pass it with `onFormatChange` to
+     * control the format.
+     */
+    format?: ColorPickerFormat;
+    /**
+     * The notation the picker starts in.
+     * @default "hex"
+     */
+    defaultFormat?: ColorPickerFormat;
+    /**
+     * Called when the format changes. Switching format also re-emits the
+     * current colour through `onValueChange` with reason `"format-change"`, so
+     * a controlled `value` never disagrees with the notation on screen.
+     */
+    onFormatChange?: (format: ColorPickerFormat) => void;
+    /**
+     * The notations `ColorPicker.Format` offers, in order. Narrow it to the one
+     * your app stores — a design tool that writes OKLCH has no use for a HEX
+     * option that silently rounds.
+     * @default ["hex", "rgb", "hsl", "oklch"]
+     */
+    formats?: readonly ColorPickerFormat[];
+    /**
+     * Whether every part ignores interaction.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the popover is open when it first mounts. Only relevant when the
+     * picker is used with `ColorPicker.Trigger` and `ColorPicker.Popup`.
+     * @default false
+     */
+    defaultOpen?: PopoverRootProps["defaultOpen"];
+    /**
+     * Whether the popover is currently open. Pass it with `onOpenChange` to
+     * control the popover.
+     */
+    open?: PopoverRootProps["open"];
+    /**
+     * Called when the popover wants to open or close.
+     */
+    onOpenChange?: PopoverRootProps["onOpenChange"];
+    /**
+     * Whether the popover takes the page over while it is open. See
+     * `Popover.Root`'s own `modal` for the three settings.
+     * @default false
+     */
+    modal?: PopoverRootProps["modal"];
+    /**
+     * The picker's parts.
+     */
+    children?: React.ReactNode;
+}
+/**
+ * Owns the colour and the format, and renders no DOM element of its own — so
+ * it takes neither `className` nor `ref`.
+ *
+ * It also renders a `Popover.Root`, which is what lets `ColorPicker.Trigger`
+ * and `ColorPicker.Popup` exist without the consumer wiring a popover by hand.
+ * A picker built out of `ColorPicker.Panel` alone simply never uses it: the
+ * popover root renders nothing until a trigger and a popup are present.
+ *
+ * ```tsx
+ * <ColorPicker.Root defaultValue="#7c3aed">
+ *   <ColorPicker.Trigger>Brand colour</ColorPicker.Trigger>
+ *   <ColorPicker.Popup>
+ *     <ColorPicker.Area />
+ *     <ColorPicker.HueSlider />
+ *     <ColorPicker.Row>
+ *       <ColorPicker.Format />
+ *       <ColorPicker.Input />
+ *     </ColorPicker.Row>
+ *   </ColorPicker.Popup>
+ * </ColorPicker.Root>
+ * ```
+ */
+export declare function ColorPickerRoot({ value, defaultValue, onValueChange, onValueCommitted, format: formatProp, defaultFormat, onFormatChange, formats, disabled, defaultOpen, open, onOpenChange, modal, children, }: ColorPickerRootProps): React.JSX.Element;
+export interface ColorPickerTriggerProps extends Omit<React.ComponentPropsWithoutRef<"button">, "className" | "color"> {
+    /**
+     * Hide the built-in swatch, for a trigger that shows the colour some other
+     * way — a filled button, an icon that inherits it.
+     * @default false
+     */
+    hideSwatch?: boolean;
+    /**
+     * The trigger's visible label. The current colour is announced after it, so
+     * a trigger with no children is still named.
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The button that opens the picker. Renders a `<button>` showing the current
+ * colour as a swatch, followed by whatever children you give it.
+ *
+ * The colour is also announced, in a visually hidden span: colour is the one
+ * thing a swatch cannot convey to a screen reader, and a trigger reading only
+ * "Brand colour" leaves out the entire answer.
+ */
+export declare const ColorPickerTrigger: React.ForwardRefExoticComponent<ColorPickerTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export interface ColorPickerPopupProps extends Omit<PopoverPopupProps, "className" | "children"> {
+    /**
+     * Render the wedge pointing back at the trigger.
+     *
+     * A boolean here where `Popover` wants a child element, because this
+     * component's children are the picker's own parts and an `Arrow` mixed in
+     * among them would be layout, not chrome. `ColorPicker.Arrow` is still
+     * exported for the rare popup that composes its own header.
+     * @default true
+     */
+    arrow?: boolean;
+    /**
+     * The picker's parts.
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional class name(s) for the inner panel — the element that owns the
+     * padding and the column layout.
+     */
+    panelClassName?: string;
+    /**
+     * Additional class name(s) for the popup surface. Applied after the
+     * internal styles so consumer utilities (e.g. Tailwind) win without needing
+     * `!important`.
+     */
+    className?: string;
+}
+/**
+ * The picker on a popover surface, anchored to `ColorPicker.Trigger`.
+ *
+ * Wraps `Popover.Popup` and takes all of its props — `side`, `align`,
+ * `sideOffset`, `initialFocus` and the rest — so placement is tuned the same
+ * way it is on a popover.
+ */
+export declare const ColorPickerPopup: React.ForwardRefExoticComponent<Omit<ColorPickerPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** The wedge pointing back at the trigger. `ColorPicker.Popup` renders one by
+ * default; this is here for a popup that turns `arrow` off and places its own. */
+export declare const ColorPickerArrow: React.ForwardRefExoticComponent<Omit<import('../popover').PopoverArrowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerPanelProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className"> {
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The picker laid out in the page rather than in a popover. Renders a `<div>`
+ * as a column, with the same padding, surface and width as
+ * `ColorPicker.Popup`'s inner panel — the two share one rule, so a picker
+ * moved from one to the other does not change shape.
+ */
+export declare const ColorPickerPanel: React.ForwardRefExoticComponent<ColorPickerPanelProps & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerRowProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className"> {
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The compact control row: eyedropper, preview, format and text field sitting
+ * on one line.
+ *
+ * A plain `<div>` rather than a Base UI part, the way `Popover.Footer` is. It
+ * exists because that row is the piece of chrome every second picker grows,
+ * and left to each consumer it is re-invented with a different gap each time —
+ * one that stops the text field from shrinking below its content and pushing
+ * the panel wider than the popup it sits in.
+ */
+export declare const ColorPickerRow: React.ForwardRefExoticComponent<ColorPickerRowProps & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerAreaProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className" | "onChange"> {
+    /**
+     * Accessible name for the horizontal axis.
+     * @default "Saturation"
+     */
+    saturationLabel?: string;
+    /**
+     * Accessible name for the vertical axis.
+     * @default "Brightness"
+     */
+    brightnessLabel?: string;
+    /**
+     * How far one arrow key moves each axis, as a fraction of the axis.
+     * `Shift` multiplies it by ten, as it does on the sliders.
+     * @default 0.01
+     */
+    step?: number;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The saturation/brightness canvas — the part that makes this a colour picker
+ * rather than a swatch list. Renders a `<div>` with a draggable thumb and two
+ * nested `<input type="range">`.
+ *
+ * The two inputs are the whole accessibility story. A 2D field has no ARIA
+ * role of its own, so it is expressed as what it actually is: two ranges that
+ * happen to share a thumb. Each is a real slider to assistive technology and
+ * to the keyboard — arrow keys, Home, End and Page Up/Down all work without
+ * this component implementing any of them — and an arrow key across the axes
+ * moves focus to the other input, so the value that changes is the value that
+ * gets announced.
+ *
+ * The canvas does NOT mirror under RTL, and that is deliberate: it is a
+ * picture of a colour space, not a line of text, and the hue that sits on the
+ * left of every other colour tool in the world should not move because the
+ * surrounding paragraph runs the other way. The hue and alpha rails DO mirror,
+ * because they are sliders and a slider's start follows the writing direction.
+ */
+export declare const ColorPickerArea: React.ForwardRefExoticComponent<ColorPickerAreaProps & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerHueSliderProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className"> {
+    /**
+     * Accessible name for the rail.
+     * @default "Hue"
+     */
+    label?: string;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The hue rail — 0° to 360°, one degree per arrow key and ten per Page Up.
+ *
+ * Hue is the axis the canvas cannot show, since the canvas is a slice through
+ * one hue. Rendering an `Area` without this leaves the user stuck in whichever
+ * hue the value arrived in.
+ */
+export declare function ColorPickerHueSlider({ label, className, style, ...props }: ColorPickerHueSliderProps): React.JSX.Element;
+export interface ColorPickerAlphaSliderProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className"> {
+    /**
+     * Accessible name for the rail.
+     * @default "Opacity"
+     */
+    label?: string;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The opacity rail — 0% to 100% over a checkerboard.
+ *
+ * Rendering it is what turns alpha on: the picker omits alpha from every
+ * format while the colour is fully opaque, so a picker without this rail emits
+ * `#7c3aed` rather than `#7c3aedff` and needs no prop to say so. A
+ * `defaultValue` that already carries alpha keeps it either way.
+ */
+export declare function ColorPickerAlphaSlider({ label, className, style, ...props }: ColorPickerAlphaSliderProps): React.JSX.Element;
+export interface ColorPickerSwatchesProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className" | "color"> {
+    /**
+     * The palette, as CSS colour strings. Anything `value` accepts works here,
+     * including translucent colours.
+     * @default DEFAULT_SWATCHES
+     */
+    colors?: readonly string[];
+    /**
+     * How many swatches per row. Also the arrow-key stride, so Up and Down move
+     * between rows rather than by one.
+     * @default 8
+     */
+    columns?: number;
+    /**
+     * Accessible name for the group.
+     * @default "Colour swatches"
+     */
+    label?: string;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * A grid of preset colours. Renders a `<div>` with `role="radiogroup"`.
+ *
+ * Radio semantics, not a row of buttons, because that is what the control
+ * actually is: a set of mutually exclusive options where at most one is
+ * current. It buys the whole keyboard convention with it — one tab stop for
+ * the group, arrow keys between swatches, and selection following focus — so a
+ * twenty-four colour palette costs a keyboard user one Tab instead of
+ * twenty-four.
+ *
+ * The colours come from `colors`; children are not read. That is what lets the
+ * group know its own order, which is what arrow keys and the single tab stop
+ * are computed from. For a palette you want to build element by element, use
+ * `ColorPicker.Swatch` on its own — outside a group each swatch is an
+ * independent toggle.
+ */
+export declare const ColorPickerSwatches: React.ForwardRefExoticComponent<ColorPickerSwatchesProps & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerSwatchProps extends Omit<React.ComponentPropsWithoutRef<"button">, "className" | "value" | "color"> {
+    /**
+     * The colour this swatch sets, as a CSS colour string.
+     */
+    value: string;
+    /**
+     * Accessible name. Defaults to the colour string, which is the only thing
+     * that is reliably true about it — a name of your own ("Brand primary") is
+     * better wherever you have one.
+     */
+    label?: string;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * One preset colour. Renders a `<button>`.
+ *
+ * Inside `ColorPicker.Swatches` it is a radio in that group. On its own it is
+ * a toggle button carrying `aria-pressed` — a lone `role="radio"` would
+ * promise a group that does not exist.
+ *
+ * Selection is decided by comparing eight-bit colour, not strings, so a swatch
+ * written `#f00` is still shown as current when the value reads
+ * `rgb(255 0 0)`.
+ */
+export declare const ColorPickerSwatch: React.ForwardRefExoticComponent<ColorPickerSwatchProps & React.RefAttributes<HTMLButtonElement>>;
+export interface ColorPickerPreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "className" | "color"> {
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * A chip filled with the current colour, over a checkerboard so a translucent
+ * value is legible. Renders a `<div>`.
+ *
+ * Decorative: `aria-hidden`, because the colour it shows is already announced
+ * by the trigger and readable in `ColorPicker.Input`, and a third announcement
+ * of the same value on every drag frame is noise.
+ */
+export declare const ColorPickerPreview: React.ForwardRefExoticComponent<ColorPickerPreviewProps & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerValueProps extends Omit<React.ComponentPropsWithoutRef<"span">, "className" | "children"> {
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * The current colour as text, in the current format. Renders a `<span>` in the
+ * mono face with tabular figures, so the readout does not change width as the
+ * digits change under a drag.
+ */
+export declare const ColorPickerValue: React.ForwardRefExoticComponent<ColorPickerValueProps & React.RefAttributes<HTMLSpanElement>>;
+export interface ColorPickerFormatProps {
+    /**
+     * Accessible name for the control.
+     * @default "Colour format"
+     */
+    label?: string;
+    /**
+     * Additional class name(s) for the trigger. Applied after the internal
+     * styles so consumer utilities (e.g. Tailwind) win without needing
+     * `!important`.
+     */
+    className?: string;
+}
+/**
+ * Picks the notation the value is written in, from the `formats` allowed on
+ * `ColorPicker.Root`. Composes this library's own `Select`.
+ *
+ * Changing it rewrites the value rather than the colour: the same colour comes
+ * back out as `#7c3aed`, `rgb(124 58 237)`, `hsl(262.1 83.3% 57.8%)` or
+ * `oklch(0.5413 0.2466 293.01)` — which is also why HEX rounds and the other
+ * three do not.
+ */
+export declare function ColorPickerFormatSelect({ label, className, }: ColorPickerFormatProps): React.JSX.Element;
+export interface ColorPickerInputProps extends Omit<React.ComponentPropsWithoutRef<"input">, "className" | "value" | "defaultValue" | "type" | "onChange"> {
+    /**
+     * Accessible name for the field.
+     * @default "Colour value"
+     */
+    label?: string;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * A text field holding the colour in the current format. Renders an `<input>`.
+ *
+ * It is the picker's precision instrument and its paste target — and, for
+ * anyone who cannot use a canvas at all, the route to an exact colour that the
+ * canvas is not.
+ *
+ * While it has focus the field keeps the text the user is typing, not the
+ * formatted value: rewriting `#7c3` to `#77cc33` mid-keystroke would move the
+ * caret and make the field impossible to type into. Every keystroke that
+ * parses is applied immediately, so the panel previews as you type; one that
+ * does not is left alone and marked `data-invalid`. Blur restores the
+ * canonical text, so an abandoned edit cannot leave the field disagreeing with
+ * the colour.
+ */
+export declare const ColorPickerInput: React.ForwardRefExoticComponent<ColorPickerInputProps & React.RefAttributes<HTMLInputElement>>;
+export interface ColorPickerEyeDropperProps extends Omit<React.ComponentPropsWithoutRef<"button">, "className"> {
+    /**
+     * Accessible name for the button.
+     * @default "Pick a colour from the screen"
+     */
+    label?: string;
+    /**
+     * Additional class name(s). Applied after the internal styles so consumer
+     * utilities (e.g. Tailwind) win without needing `!important`.
+     */
+    className?: string;
+}
+/**
+ * Samples a colour from anywhere on the screen, through the browser's
+ * EyeDropper API. Renders a `<button>` — or nothing at all where the API is
+ * missing, which today is Firefox and every browser on iOS.
+ *
+ * Rendering nothing is the point: this is a shortcut to a colour the rest of
+ * the picker can already reach, so its absence costs a user nothing, while a
+ * button that opens no eyedropper costs them a click and their confidence in
+ * the rest of the panel. The detection runs in an effect rather than during
+ * render because the server cannot know the answer, and guessing there is what
+ * produces a hydration mismatch.
+ */
+export declare const ColorPickerEyeDropper: React.ForwardRefExoticComponent<ColorPickerEyeDropperProps & React.RefAttributes<HTMLButtonElement>>;
+export interface ColorPickerHiddenInputProps extends Omit<React.ComponentPropsWithoutRef<"input">, "type" | "value" | "onChange"> {
+    /**
+     * The field name the colour is submitted under.
+     */
+    name: string;
+}
+/**
+ * Submits the colour with a form. Renders `<input type="hidden">`.
+ *
+ * Place it next to `ColorPicker.Trigger`, NOT inside `ColorPicker.Popup`. The
+ * popup is portalled to `<body>` and unmounted while it is closed, so a hidden
+ * input in there is outside the form's element tree even when it exists, and
+ * missing entirely by the time anything is submitted.
+ */
+export declare const ColorPickerHiddenInput: React.ForwardRefExoticComponent<ColorPickerHiddenInputProps & React.RefAttributes<HTMLInputElement>>;
+/**
+ * A colour picker: a saturation/brightness canvas, hue and opacity rails, a
+ * preset palette, an eyedropper and a text field that reads and writes four
+ * CSS notations.
+ *
+ * Base UI has no colour-picker primitive, so this one is built here — on
+ * `Popover` for the anchored surface and on Base UI's `Slider` for the two
+ * rails, which is where the keyboard, the pointer capture and the RTL flip
+ * come from.
+ *
+ * ```tsx
+ * <ColorPicker.Root defaultValue="#7c3aed">
+ *   <ColorPicker.Trigger>Brand colour</ColorPicker.Trigger>
+ *   <ColorPicker.Popup>
+ *     <ColorPicker.Area />
+ *     <ColorPicker.HueSlider />
+ *     <ColorPicker.AlphaSlider />
+ *     <ColorPicker.Swatches />
+ *     <ColorPicker.Row>
+ *       <ColorPicker.EyeDropper />
+ *       <ColorPicker.Format />
+ *       <ColorPicker.Input />
+ *     </ColorPicker.Row>
+ *   </ColorPicker.Popup>
+ * </ColorPicker.Root>
+ * ```
+ *
+ * Every part is opt-in. A picker that is nothing but a palette is
+ * `Root` + `Swatches`; one with no transparency simply leaves out
+ * `AlphaSlider`, and the value it emits has no alpha channel in it.
+ *
+ * Styling is driven by `data-*` attributes and `--forte-color-picker-*` custom
+ * properties, so it can be re-skinned from plain CSS or targeted with Tailwind
+ * arbitrary variants (`data-[selected]:...`) without wrapping.
+ */
+export declare const ColorPicker: {
+    Root: typeof ColorPickerRoot;
+    Trigger: React.ForwardRefExoticComponent<ColorPickerTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+    Popup: React.ForwardRefExoticComponent<Omit<ColorPickerPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+    Arrow: React.ForwardRefExoticComponent<Omit<import('../popover').PopoverArrowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+    Panel: React.ForwardRefExoticComponent<ColorPickerPanelProps & React.RefAttributes<HTMLDivElement>>;
+    Row: React.ForwardRefExoticComponent<ColorPickerRowProps & React.RefAttributes<HTMLDivElement>>;
+    Area: React.ForwardRefExoticComponent<ColorPickerAreaProps & React.RefAttributes<HTMLDivElement>>;
+    HueSlider: typeof ColorPickerHueSlider;
+    AlphaSlider: typeof ColorPickerAlphaSlider;
+    Swatches: React.ForwardRefExoticComponent<ColorPickerSwatchesProps & React.RefAttributes<HTMLDivElement>>;
+    Swatch: React.ForwardRefExoticComponent<ColorPickerSwatchProps & React.RefAttributes<HTMLButtonElement>>;
+    Preview: React.ForwardRefExoticComponent<ColorPickerPreviewProps & React.RefAttributes<HTMLDivElement>>;
+    Value: React.ForwardRefExoticComponent<ColorPickerValueProps & React.RefAttributes<HTMLSpanElement>>;
+    Format: typeof ColorPickerFormatSelect;
+    Input: React.ForwardRefExoticComponent<ColorPickerInputProps & React.RefAttributes<HTMLInputElement>>;
+    EyeDropper: React.ForwardRefExoticComponent<ColorPickerEyeDropperProps & React.RefAttributes<HTMLButtonElement>>;
+    HiddenInput: React.ForwardRefExoticComponent<ColorPickerHiddenInputProps & React.RefAttributes<HTMLInputElement>>;
+};

package/dist/components/color-picker/ColorPicker.js

@@ -0,0 +1,4 @@
+"use client";
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _ } from "../../ColorPicker-B-eCI31W.js";
+import { DEFAULT_SWATCHES as v } from "./color.js";
+export { h as ColorPicker, u as ColorPickerAlphaSlider, p as ColorPickerArea, s as ColorPickerArrow, t as ColorPickerEyeDropper, d as ColorPickerFormatSelect, m as ColorPickerHiddenInput, n as ColorPickerHueSlider, c as ColorPickerInput, g as ColorPickerPanel, r as ColorPickerPopup, i as ColorPickerPreview, f as ColorPickerRoot, l as ColorPickerRow, o as ColorPickerSwatch, a as ColorPickerSwatches, e as ColorPickerTrigger, _ as ColorPickerValue, v as DEFAULT_SWATCHES };

package/dist/components/color-picker/color.d.ts

@@ -0,0 +1,102 @@
+/** The notations `ColorPicker` can read back and write out. */
+export type ColorPickerFormat = "hex" | "rgb" | "hsl" | "oklch";
+/** The picker's internal model. `h` is degrees; `s`, `v` and `a` are 0-1. */
+export interface Hsva {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+}
+/** Eight-bit sRGB with an alpha channel. Channels are floats until output. */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export declare function hsvaToRgba({ h, s, v, a }: Hsva): Rgba;
+export declare function rgbaToHsva({ r, g, b, a }: Rgba): Hsva;
+export declare function hsvaToHsl({ h, s, v }: Hsva): {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare function hslToHsv(h: number, s: number, l: number, a: number): Hsva;
+export declare function rgbaToOklch({ r, g, b, a }: Rgba): {
+    l: number;
+    c: number;
+    h: number;
+    a: number;
+};
+/**
+ * OKLCH to sRGB, gamut-mapped rather than clipped.
+ *
+ * `oklch(0.7 0.4 30)` names a colour no screen in this gamut can show. Clipping
+ * each channel at 0 and 1 — the obvious one-liner — changes the hue as well as
+ * the chroma, so an author's out-of-gamut orange arrives as a different colour
+ * family. Reducing chroma toward the achromatic axis at constant L and H keeps
+ * the hue the author asked for and gives up only the saturation the display
+ * could not have shown anyway. Sixteen bisection steps put the answer within
+ * ~6e-6 of the gamut boundary, well under an eight-bit step.
+ */
+export declare function oklchToRgba(l: number, c: number, h: number, a: number): Rgba;
+/**
+ * Whether black or white reads better ON this colour — for the tick drawn
+ * inside a selected swatch and the ring around the area's thumb, both of which
+ * sit on colour the user chose and nothing else can be known about.
+ *
+ * Alpha is ignored on purpose: what a translucent swatch is composited over is
+ * whatever the checkerboard and the panel happen to be, which is not something
+ * this function can see, and the answer only changes near the middle of the
+ * ramp where either choice is legible.
+ */
+export declare function onColor({ r, g, b }: Rgba): "black" | "white";
+/**
+ * Reads a CSS colour string into the picker's model.
+ *
+ * Accepts `#hex` (3, 4, 6 or 8 digits), `rgb()`/`rgba()`, `hsl()`/`hsla()`,
+ * `oklch()`, `oklab()` and the keyword `transparent`, in both the legacy
+ * comma-separated and the modern space-separated forms. Returns `null` for
+ * anything else — including named colours, which would need the full 148-entry
+ * CSS table to be shipped in every bundle that touches the picker, for input
+ * the picker itself never produces.
+ *
+ * `null` is a normal outcome, not an error: it is what the text field's
+ * `data-invalid` state is driven by while a value is half-typed.
+ */
+export declare function parseColor(input: string): Hsva | null;
+/**
+ * The picker's model as a CSS colour string.
+ *
+ * Alpha is omitted when the colour is fully opaque, in every format. That is
+ * the one rule worth stating out loud: it means a picker whose alpha rail was
+ * never touched — or never rendered — emits `#7c3aed` and not `#7c3aedff`, so
+ * an author who does not want alpha simply never gets any, without a prop
+ * saying so. `rgb()` also stays `rgb()` rather than becoming `rgba()`, which
+ * CSS Color 4 made an alias of it.
+ *
+ * Precision is set by what each notation can hold, not by taste: `hex` is
+ * eight-bit and exact, while `hsl` and `oklch` are rounded to the point where
+ * re-parsing lands on the same eight-bit colour. It is not what makes the
+ * picker's own round trip stable, though — see the note on `emittedRef` in
+ * ColorPicker.tsx.
+ */
+export declare function formatColor(hsva: Hsva, format: ColorPickerFormat): string;
+/** `rgb()` with alpha — what the CSS custom properties carry, since a gradient
+ * stop and a preview swatch both need one string that is always valid. */
+export declare function toCssColor(hsva: Hsva): string;
+/** Two colours are the same swatch when they are the same eight-bit colour.
+ * Comparing the model instead would call `#000` and `hsl(200 0% 0%)` different,
+ * and neither the eye nor the output string can tell them apart. */
+export declare function sameColor(a: Rgba, b: Rgba): boolean;
+/**
+ * The palette `ColorPicker.Swatches` falls back to: eight neutrals, eight warm
+ * hues and eight cool ones, in three rows of eight.
+ *
+ * Deliberately NOT built from the forte-ui ramp. Those tokens are `var()`
+ * references that resolve differently per theme scope and per light/dark, and a
+ * picker has to hand back a concrete colour the consumer can store — a swatch
+ * that means one thing in dark mode and another in light is not a colour, it is
+ * a variable. An app with a brand palette passes its own `colors`.
+ */
+export declare const DEFAULT_SWATCHES: readonly string[];