@instruments/materia-ui 0.1.0

package/dist/compositions/color-palette/color-palette-root.js

@@ -0,0 +1,88 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { defaultRenderLink, PaletteRow } from "./color-palette-parts.js";
+import { sortPaletteItems } from "./palette-sort.js";
+/** Controlled/uncontrolled sort, direction, and selection state + handlers. */
+const usePaletteControls = ({ defaultDirection, defaultSelectedIds, defaultSort, directionProp, onDirectionChange, onSelectedIdsChange, onSortChange, selectedIdsProp, sortProp, }) => {
+    const [internalSort, setInternalSort] = useState(defaultSort);
+    const [internalDirection, setInternalDirection] = useState(defaultDirection);
+    const [internalSelectedIds, setInternalSelectedIds] = useState(defaultSelectedIds ?? []);
+    const sort = sortProp ?? internalSort;
+    const direction = directionProp ?? internalDirection;
+    const selectedIds = selectedIdsProp ?? internalSelectedIds;
+    const handleSortChange = (next) => {
+        setInternalSort(next);
+        onSortChange?.(next);
+    };
+    const handleDirectionChange = (next) => {
+        setInternalDirection(next);
+        onDirectionChange?.(next);
+    };
+    const handleToggleSelected = (id) => {
+        const next = selectedIds.includes(id)
+            ? selectedIds.filter((selectedId) => selectedId !== id)
+            : [...selectedIds, id];
+        setInternalSelectedIds(next);
+        onSelectedIdsChange?.(next);
+    };
+    return {
+        direction,
+        handleDirectionChange,
+        handleSortChange,
+        handleToggleSelected,
+        selectedIds,
+        sort,
+    };
+};
+/**
+ * Stacked colour palette in the style of the Dropbox brand site: a row of
+ * overlapping, bottom-anchored square cards cropped to 16:9. Hovering
+ * or focusing a card smoothly raises it and reveals a search action that
+ * deep-links into the colours search page.
+ *
+ * The component renders only the swatch row - no card, heading, or CTA
+ * chrome. Compose those around it (a `<section>`, a title, a sample button
+ * wired to `onSelectedIdsChange`) when a surface calls for them.
+ *
+ * Cards can be flat colours, gradients, or images (see ColorPaletteItem).
+ * Image cards need a `searchHex` to be clickable.
+ *
+ * With `selectable`, clicking anywhere on a card toggles it in and out of
+ * the selection instead of linking out; selected cards keep a check
+ * visible at rest, and the selection surfaces through `onSelectedIdsChange`.
+ *
+ * @example
+ * ```tsx
+ * <ColorPalette
+ *   items={[
+ *     { kind: "color", hex: "#7B2D26", name: "Rust" },
+ *     { kind: "gradient", from: "#C97B43", to: "#F2C879" },
+ *     { kind: "image", src: "/oak.jpg", searchHex: "#8C5A3C" },
+ *   ]}
+ * />
+ * ```
+ *
+ * @bestPractice Describe cards as `items` (`kind: "color" | "gradient" | "image"`), not hand-built markup - the component owns the overlap, hover-raise, and deep-link-to-search behaviour.
+ * @bestPractice Give every `image` card a `searchHex`, otherwise it can't be searched or selected - flat colours and gradients derive theirs automatically.
+ * @bestPractice Pass `renderLink` (e.g. wrapping `next/link`) for client-side nav - the built-in links are plain `<a>`; the callback must return a single anchor element.
+ * @category catalogue
+ */
+const ColorPalette = ({ items, sort: sortProp, defaultSort = "original", onSortChange, direction: directionProp, defaultDirection = "left-first", onDirectionChange, showSettings = false, selectable = false, selectedIds: selectedIdsProp, defaultSelectedIds, onSelectedIdsChange, searchBasePath = "/colors", searchLabel = "Search this color", renderLink = defaultRenderLink, className, }) => {
+    const { direction, handleDirectionChange, handleSortChange, handleToggleSelected, selectedIds, sort, } = usePaletteControls({
+        defaultDirection,
+        defaultSelectedIds,
+        defaultSort,
+        directionProp,
+        onDirectionChange,
+        onSelectedIdsChange,
+        onSortChange,
+        selectedIdsProp,
+        sortProp,
+    });
+    const sortedItems = useMemo(() => sortPaletteItems(items, sort), [items, sort]);
+    // The row sizes itself to the square cards, so the space above the
+    // resting 16:9 band is exactly the headroom a fully surfaced card needs.
+    return (_jsx(PaletteRow, { className: className, direction: direction, items: items, onDirectionChange: handleDirectionChange, onSortChange: handleSortChange, onToggleSelected: handleToggleSelected, renderLink: renderLink, searchBasePath: searchBasePath, searchLabel: searchLabel, selectable: selectable, selectedIds: selectedIds, showSettings: showSettings, sort: sort, sortedItems: sortedItems }));
+};
+export { ColorPalette };

package/dist/compositions/color-palette/palette-card.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import type { ColorPaletteLinkProps } from "./palette-helpers.js";
+import type { ColorPaletteItem, PaletteDirection } from "./palette-sort.js";
+interface PaletteCardProps {
+    item: ColorPaletteItem;
+    index: number;
+    total: number;
+    direction: PaletteDirection;
+    hoveredIndex: number | null;
+    onHover: (index: number | null) => void;
+    searchBasePath: string;
+    searchLabel: string;
+    renderLink: (props: ColorPaletteLinkProps) => ReactNode;
+    selectable: boolean;
+    selected: boolean;
+    onToggleSelected: () => void;
+}
+export declare const PaletteCard: ({ item, index, total, direction, hoveredIndex, onHover, searchBasePath, searchLabel, renderLink, selectable, selected, onToggleSelected, }: PaletteCardProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/color-palette/palette-card.js

@@ -0,0 +1,77 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Search } from "lucide-react";
+import { Flex } from "../../components/flex.js";
+import { Icon } from "../../components/icon.js";
+import { focusRing } from "../../tokens/focus-ring.js";
+import { cn } from "../../utils/cn.js";
+import { hasText } from "../../utils/type-guards.js";
+import { CASCADE_RISE, getItemFill, hrefHasValue, labelToneClassName, REST_SINK, } from "./palette-helpers.js";
+import { PaletteSelectIndicator } from "./palette-select-indicator.js";
+import { buildSearchHref, stackZIndex } from "./palette-sort.js";
+/** Image fill (when present) and the hover-revealed label row. */
+const PaletteCardContent = ({ href, item, labelText, selectable, }) => (_jsxs(_Fragment, { children: [item.kind === "image" && (_jsx("img", { alt: item.alt ?? item.name ?? "", className: "absolute inset-0 size-full object-cover", height: 1, src: item.src, width: 1 })), hasText(labelText) && (_jsxs(Flex, { align: "center", as: "span", className: cn("text-paragraph-sm pointer-events-none absolute top-4 left-4 gap-1.5 font-medium whitespace-nowrap", 
+            // Clear the selection indicator instead of running under it.
+            selectable ? "right-12" : "right-4", "transition-opacity-translate duration-normal translate-y-1 opacity-0", "group-hover/swatch:translate-y-0 group-hover/swatch:opacity-100", "group-has-focus-visible/swatch:translate-y-0 group-has-focus-visible/swatch:opacity-100", "motion-reduce:translate-y-0 motion-reduce:transition-none", labelToneClassName(item)), children: [hasText(href) && _jsx(Icon, { className: "shrink-0", icon: Search, size: "xs" }), labelText] }))] }));
+/**
+ * The interactive (or static) card surface. Top corners only: the bottom
+ * edge always reads as cropped, both at rest (sunken below the clip) and
+ * fully surfaced (flush with it).
+ */
+const PaletteCardSurface = ({ content, href, index, item, onHover, onToggleSelected, renderLink, searchActionLabel, selectActionLabel, selectable, selected, surfaceClassName, }) => {
+    if (selectable) {
+        return (_jsxs("button", { "aria-label": selectActionLabel, "aria-pressed": selected, className: cn(surfaceClassName, "cursor-pointer"), onBlur: () => {
+                onHover(null);
+            }, onClick: onToggleSelected, onFocus: () => {
+                onHover(index);
+            }, style: getItemFill(item), type: "button", children: [content, _jsx(PaletteSelectIndicator, { item: item, selected: selected })] }));
+    }
+    if (hasText(href)) {
+        return renderLink({
+            "aria-label": searchActionLabel,
+            children: content,
+            className: surfaceClassName,
+            href,
+            onBlur: () => {
+                onHover(null);
+            },
+            onFocus: () => {
+                onHover(index);
+            },
+            style: getItemFill(item),
+        });
+    }
+    return (_jsx("div", { className: surfaceClassName, style: getItemFill(item), children: content }));
+};
+export const PaletteCard = ({ item, index, total, direction, hoveredIndex, onHover, searchBasePath, searchLabel, renderLink, selectable, selected, onToggleSelected, }) => {
+    const href = buildSearchHref(item, searchBasePath);
+    // The visible hover label is just the colour name; the accessible name
+    // stays descriptive ("Search for Honey" / "Select Honey").
+    const labelText = item.name ?? (hasText(href) ? searchLabel : undefined);
+    const searchActionLabel = hasText(item.name)
+        ? `Search for ${item.name}`
+        : searchLabel;
+    const selectActionLabel = `Select ${item.name ?? (item.kind === "color" ? item.hex : "color")}`;
+    const distance = hoveredIndex === null ? null : Math.abs(index - hoveredIndex);
+    const rise = distance === null ? 0 : (CASCADE_RISE[distance] ?? 0);
+    const style = {
+        // The square card sinks below the container bottom (cropped by the
+        // row's clip-path) and surfaces on hover; translate percentages are
+        // relative to the card itself, so the geometry scales with card width.
+        translate: `0 ${(REST_SINK - rise) * 100}%`,
+        // Stacking order stays put even while hovered - the raised card clears
+        // its neighbours vertically, never by jumping in front of them.
+        zIndex: stackZIndex(index, total, direction),
+    };
+    // The surface paints the fill and clips to the card shape; the wrapper
+    // owns sizing and motion. In selectable mode the whole card is the
+    // toggle, so the indicator nests inside it instead of being a sibling
+    // button.
+    const surfaceClassName = cn("absolute inset-0 overflow-hidden rounded-t-2xl", (selectable || hrefHasValue(href)) &&
+        // Surface clips to the card shape (`overflow-hidden`), so the ring must be
+        // inset or it would be clipped away (WCAG 2.4.7).
+        cn(focusRing(), "focus-visible:ring-inset"));
+    return (_jsx("div", { className: cn("group/swatch relative aspect-square min-w-52 flex-1", "ease-sheet duration-normal transition-transform will-change-transform motion-reduce:transition-none", index > 0 && "-ml-44"), onMouseEnter: () => {
+            onHover(index);
+        }, style: style, children: _jsx(PaletteCardSurface, { content: _jsx(PaletteCardContent, { href: href, item: item, labelText: labelText, selectable: selectable }), href: href, index: index, item: item, onHover: onHover, onToggleSelected: onToggleSelected, renderLink: renderLink, searchActionLabel: searchActionLabel, selectActionLabel: selectActionLabel, selectable: selectable, selected: selected, surfaceClassName: surfaceClassName }) }));
+};

package/dist/compositions/color-palette/palette-helpers.d.ts

@@ -0,0 +1,45 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ColorPaletteItem, PaletteDirection, PaletteSort } from "./palette-sort.js";
+export declare const isPaletteSort: (value: string) => value is PaletteSort;
+export declare const isPaletteDirection: (value: string) => value is PaletteDirection;
+/**
+ * Href "has a value" check matching the original 2-clause guard: an href is
+ * `string | null`, and this treats null as present (only undefined and ""
+ * count as missing) to preserve the resting class output exactly.
+ */
+export declare const hrefHasValue: (href: string | null | undefined) => boolean;
+/**
+ * Every card is a 1:1 square that sits sunken below the container bottom by
+ * this fraction of its own size, where the row's clip-path crops it. The
+ * visible portion at rest is therefore exactly 16:9 (9/16 of the square
+ * shows, 7/16 hides). Hovering translates a card back up: fully surfaced,
+ * it reads as the full 1:1 square.
+ */
+export declare const REST_SINK: number;
+/**
+ * How much of the sunken fraction surfaces on hover, by distance from the
+ * hovered card (fractions of the card's own size): the hovered card
+ * surfaces completely (16:9 → 1:1) and neighbours cascade with falloff.
+ * Stacking order never changes on hover, so the hovered card's label clears
+ * its neighbours purely by out-rising them.
+ */
+export declare const CASCADE_RISE: number[];
+export interface ColorPaletteLinkProps {
+    href: string;
+    className?: string;
+    style?: CSSProperties;
+    "aria-label": string;
+    children: ReactNode;
+    onFocus?: () => void;
+    onBlur?: () => void;
+}
+export declare const getItemFill: (item: ColorPaletteItem) => CSSProperties;
+export declare const defaultRenderLink: ({ children, ...props }: ColorPaletteLinkProps) => import("react").JSX.Element;
+/** Hover label treatment per fill kind, picked for contrast. */
+export declare const labelToneClassName: (item: ColorPaletteItem) => string;
+/**
+ * Selection indicator tone per fill kind, mirroring the hover label
+ * treatment: resting circles sit slightly transparent and sharpen when the
+ * card is hovered, the selected check reads at full strength.
+ */
+export declare const indicatorToneClassName: (item: ColorPaletteItem, selected: boolean) => string;

package/dist/compositions/color-palette/palette-helpers.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getItemLightness } from "./palette-sort.js";
+export const isPaletteSort = (value) => value === "original" ||
+    value === "light-to-dark" ||
+    value === "dark-to-light";
+export const isPaletteDirection = (value) => value === "left-first" || value === "right-first";
+/**
+ * Href "has a value" check matching the original 2-clause guard: an href is
+ * `string | null`, and this treats null as present (only undefined and ""
+ * count as missing) to preserve the resting class output exactly.
+ */
+export const hrefHasValue = (href) => href !== undefined && href !== "";
+/**
+ * Every card is a 1:1 square that sits sunken below the container bottom by
+ * this fraction of its own size, where the row's clip-path crops it. The
+ * visible portion at rest is therefore exactly 16:9 (9/16 of the square
+ * shows, 7/16 hides). Hovering translates a card back up: fully surfaced,
+ * it reads as the full 1:1 square.
+ */
+export const REST_SINK = 7 / 16;
+/**
+ * How much of the sunken fraction surfaces on hover, by distance from the
+ * hovered card (fractions of the card's own size): the hovered card
+ * surfaces completely (16:9 → 1:1) and neighbours cascade with falloff.
+ * Stacking order never changes on hover, so the hovered card's label clears
+ * its neighbours purely by out-rising them.
+ */
+export const CASCADE_RISE = [REST_SINK, 0.12, 0.05];
+export const getItemFill = (item) => {
+    if (item.kind === "color") {
+        return { backgroundColor: item.hex };
+    }
+    if (item.kind === "gradient") {
+        return {
+            backgroundImage: `linear-gradient(${item.angle ?? 180}deg, ${item.from}, ${item.to})`,
+        };
+    }
+    return {};
+};
+export const defaultRenderLink = ({ children, ...props }) => _jsx("a", { ...props, children: children });
+/** Light fills take dark adornments; one threshold for label and indicator. */
+const hasLightFill = (item) => getItemLightness(item) > 70;
+/** Hover label treatment per fill kind, picked for contrast. */
+export const labelToneClassName = (item) => {
+    if (item.kind === "image") {
+        return "w-fit rounded-full bg-black/40 px-3 py-1.5 text-white";
+    }
+    return hasLightFill(item) ? "text-black/80" : "text-white/90";
+};
+/**
+ * Selection indicator tone per fill kind, mirroring the hover label
+ * treatment: resting circles sit slightly transparent and sharpen when the
+ * card is hovered, the selected check reads at full strength.
+ */
+export const indicatorToneClassName = (item, selected) => {
+    if (item.kind === "image") {
+        return "bg-black/40 text-white";
+    }
+    if (hasLightFill(item)) {
+        return selected
+            ? "text-black/90"
+            : "text-black/70 group-hover/swatch:text-black/90";
+    }
+    return selected
+        ? "text-white"
+        : "text-white/80 group-hover/swatch:text-white";
+};

package/dist/compositions/color-palette/palette-row.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import type { ColorPaletteLinkProps } from "./palette-helpers.js";
+import type { ColorPaletteItem, PaletteDirection, PaletteSort } from "./palette-sort.js";
+interface PaletteRowProps {
+    className?: string | undefined;
+    direction: PaletteDirection;
+    items: ColorPaletteItem[];
+    onDirectionChange: (direction: PaletteDirection) => void;
+    onSortChange: (sort: PaletteSort) => void;
+    onToggleSelected: (id: string) => void;
+    renderLink: (props: ColorPaletteLinkProps) => ReactNode;
+    searchBasePath: string;
+    searchLabel: string;
+    selectable: boolean;
+    selectedIds: string[];
+    showSettings: boolean;
+    sort: PaletteSort;
+    sortedItems: ColorPaletteItem[];
+}
+/**
+ * The bottom-anchored row of overlapping cards (plus the optional settings
+ * popover). Owns the transient hover index that drives the rise cascade.
+ */
+export declare const PaletteRow: ({ className, direction, items, onDirectionChange, onSortChange, onToggleSelected, renderLink, searchBasePath, searchLabel, selectable, selectedIds, showSettings, sort, sortedItems, }: PaletteRowProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/color-palette/palette-row.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Flex } from "../../components/flex.js";
+import { cn } from "../../utils/cn.js";
+import { PaletteCard } from "./palette-card.js";
+import { PaletteSettings } from "./palette-settings.js";
+import { getPaletteItemId } from "./palette-sort.js";
+/**
+ * The bottom-anchored row of overlapping cards (plus the optional settings
+ * popover). Owns the transient hover index that drives the rise cascade.
+ */
+export const PaletteRow = ({ className, direction, items, onDirectionChange, onSortChange, onToggleSelected, renderLink, searchBasePath, searchLabel, selectable, selectedIds, showSettings, sort, sortedItems, }) => {
+    const [hoveredIndex, setHoveredIndex] = useState(null);
+    const selectedIdsSet = new Set(selectedIds);
+    return (_jsxs("div", { className: cn("relative w-full", className), children: [showSettings && (_jsx(PaletteSettings, { direction: direction, onDirectionChange: onDirectionChange, onSortChange: onSortChange, sort: sort })), _jsx(Flex, { align: "flex-end", className: "w-full [clip-path:inset(-8px_-8px_0_-8px)]", onMouseLeave: () => {
+                    setHoveredIndex(null);
+                }, children: sortedItems.map((item, index) => {
+                    // indexOf recovers the original position, keeping ids stable
+                    // across sorts (sortPaletteItems preserves item references).
+                    const id = getPaletteItemId(item, items.indexOf(item));
+                    return (_jsx(PaletteCard, { direction: direction, hoveredIndex: hoveredIndex, index: index, item: item, onHover: setHoveredIndex, onToggleSelected: () => {
+                            onToggleSelected(id);
+                        }, renderLink: renderLink, searchBasePath: searchBasePath, searchLabel: searchLabel, selectable: selectable, selected: selectedIdsSet.has(id), total: sortedItems.length }, id));
+                }) })] }));
+};

package/dist/compositions/color-palette/palette-select-indicator.d.ts

@@ -0,0 +1,14 @@
+import type { ColorPaletteItem } from "./palette-sort.js";
+interface PaletteSelectIndicatorProps {
+    item: ColorPaletteItem;
+    selected: boolean;
+}
+/**
+ * Selection readout in the card's top-right corner: an empty circle on
+ * hover, a check once selected. Purely visual - the whole card is the
+ * toggle. Selected checks stay visible at rest so the current selection
+ * reads at a glance; the check pops in with a subtle scale overshoot
+ * (skipped under reduced motion).
+ */
+export declare const PaletteSelectIndicator: ({ item, selected, }: PaletteSelectIndicatorProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/color-palette/palette-select-indicator.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Circle, CircleCheck } from "lucide-react";
+import { Center } from "../../components/center.js";
+import { Icon } from "../../components/icon.js";
+import { cn } from "../../utils/cn.js";
+import { indicatorToneClassName } from "./palette-helpers.js";
+/**
+ * Selection readout in the card's top-right corner: an empty circle on
+ * hover, a check once selected. Purely visual - the whole card is the
+ * toggle. Selected checks stay visible at rest so the current selection
+ * reads at a glance; the check pops in with a subtle scale overshoot
+ * (skipped under reduced motion).
+ */
+export const PaletteSelectIndicator = ({ item, selected, }) => (_jsx(Center, { "aria-hidden": true, as: "span", className: cn("absolute top-3 right-3.5 size-7 rounded-full", "transition-opacity-scale-color-bg duration-normal group-active/swatch:scale-90 motion-reduce:transition-none", "opacity-0 group-hover/swatch:opacity-100 group-has-focus-visible/swatch:opacity-100", indicatorToneClassName(item, selected), selected && "opacity-100"), inline: true, children: selected ? (_jsx(Icon, { className: "animate-in fade-in zoom-in-75 duration-normal ease-out motion-reduce:animate-none", icon: CircleCheck, size: "lg" })) : (_jsx(Icon, { icon: Circle, size: "lg" })) }));

package/dist/compositions/color-palette/palette-settings.d.ts

@@ -0,0 +1,9 @@
+import type { PaletteDirection, PaletteSort } from "./palette-sort.js";
+interface PaletteSettingsProps {
+    sort: PaletteSort;
+    onSortChange: (sort: PaletteSort) => void;
+    direction: PaletteDirection;
+    onDirectionChange: (direction: PaletteDirection) => void;
+}
+export declare const PaletteSettings: ({ sort, onSortChange, direction, onDirectionChange, }: PaletteSettingsProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/color-palette/palette-settings.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Popover, PopoverContent, PopoverTrigger, } from "@instruments/materia-ui/components/popover";
+import { SegmentedControl, SegmentedControlItem, } from "@instruments/materia-ui/components/segmented-control";
+import { SlidersHorizontal } from "lucide-react";
+export const PaletteSettings = ({ sort, onSortChange, direction, onDirectionChange, }) => (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { render: _jsx(Button, { emphasis: "ghost", "aria-label": "Palette settings", className: "absolute top-0 right-0 z-50", icon: SlidersHorizontal, size: "icon-sm", square: true }) }), _jsx(PopoverContent, { align: "end", className: "w-auto", side: "bottom", children: _jsxs(Flex, { direction: "column", gap: "base", children: [_jsxs(Flex, { className: "gap-1.5", direction: "column", children: [_jsx("span", { className: "text-muted-foreground text-caption font-medium", children: "Sort" }), _jsxs(SegmentedControl, { onValueChange: onSortChange, size: "sm", value: sort, children: [_jsx(SegmentedControlItem, { value: "original", children: "Original" }), _jsx(SegmentedControlItem, { value: "light-to-dark", children: "Light to dark" }), _jsx(SegmentedControlItem, { value: "dark-to-light", children: "Dark to light" })] })] }), _jsxs(Flex, { className: "gap-1.5", direction: "column", children: [_jsx("span", { className: "text-muted-foreground text-caption font-medium", children: "Stack" }), _jsxs(SegmentedControl, { onValueChange: onDirectionChange, size: "sm", value: direction, children: [_jsx(SegmentedControlItem, { value: "left-first", children: "Left on top" }), _jsx(SegmentedControlItem, { value: "right-first", children: "Right on top" })] })] })] }) })] }));

package/dist/compositions/color-palette/palette-sort.d.ts

@@ -0,0 +1,72 @@
+interface ColorPaletteItemBase {
+    /** Stable key; falls back to kind plus original index (getPaletteItemId) */
+    id?: string | undefined;
+    /** Display name, e.g. "Rust" - shown on hover and used in the aria-label */
+    name?: string | undefined;
+    /**
+     * Hex used for the search link and light/dark sorting.
+     * Required for image items to be clickable; optional override for the rest.
+     */
+    searchHex?: string | undefined;
+}
+type ColorPaletteItem = (ColorPaletteItemBase & {
+    kind: "color";
+    hex: string;
+}) | (ColorPaletteItemBase & {
+    kind: "gradient";
+    from: string;
+    to: string;
+    /** Gradient angle in degrees (default 180 = top to bottom) */
+    angle?: number;
+}) | (ColorPaletteItemBase & {
+    kind: "image";
+    src: string;
+    alt?: string;
+});
+type PaletteSort = "original" | "light-to-dark" | "dark-to-light";
+type PaletteDirection = "left-first" | "right-first";
+/**
+ * HSL lightness (0–100) used for light/dark sorting and label contrast.
+ * Images without a searchHex fall back to mid lightness so they sort neutrally.
+ */
+declare const getItemLightness: (item: ColorPaletteItem) => number;
+/**
+ * Stable copy-sort of palette items by lightness. "original" returns the
+ * input array untouched.
+ */
+declare const sortPaletteItems: (items: ColorPaletteItem[], sort: PaletteSort) => ColorPaletteItem[];
+/**
+ * z-index for a card at a render position. Direction controls which end of
+ * the row stacks on top: "left-first" means the leftmost card overlaps its
+ * neighbour to the right, and vice versa.
+ */
+declare const stackZIndex: (index: number, count: number, direction: PaletteDirection) => number;
+/**
+ * Selection/render identity for an item: its explicit id, falling back to
+ * its kind plus original (pre-sort) index. Provide explicit ids when
+ * selection must survive item reordering.
+ */
+declare const getPaletteItemId: (item: ColorPaletteItem, index: number) => string;
+/**
+ * Hex an item resolves to for searching and sampling: searchHex when set,
+ * otherwise the fill (gradients fall back to their start stop). Null for
+ * images without a searchHex.
+ */
+declare const getSampleHex: (item: ColorPaletteItem) => string | null;
+/**
+ * Deep link into the colours search page for an item, or null when the item
+ * has no searchable colour (e.g. an image without a searchHex).
+ *
+ * URL contract of the consuming app's colours page:
+ * `?mode=color&hex=#rrggbb` and `?mode=gradient&gradientStart=…&gradientEnd=…`.
+ */
+declare const buildSearchHref: (item: ColorPaletteItem, basePath?: string) => string | null;
+/**
+ * Deep link for sampling a set of items. A single item reuses the
+ * buildSearchHref contract (color/gradient modes); several items deep-link
+ * into the colours page palette mode: `?mode=palette&colors=#a,#b`
+ * (comma-joined, deduped, unsampleable items skipped). Null when nothing
+ * is sampleable.
+ */
+declare const buildSampleHref: (items: ColorPaletteItem[], basePath?: string) => string | null;
+export { buildSampleHref, buildSearchHref, type ColorPaletteItem, getItemLightness, getPaletteItemId, getSampleHex, type PaletteDirection, type PaletteSort, sortPaletteItems, stackZIndex, };

package/dist/compositions/color-palette/palette-sort.js

@@ -0,0 +1,133 @@
+import { getHexLightness } from "../../data/material-colors.js";
+/**
+ * Normalise a hex colour to `#rrggbb` lowercase, matching how the colours
+ * page serializes its `hex` query param.
+ */
+const normalizeHex = (hex) => {
+    const value = hex.startsWith("#") ? hex : `#${hex}`;
+    return value.toLowerCase();
+};
+/** getHexLightness expects input without the leading `#`. */
+const hexLightness = (hex) => getHexLightness(hex.replace("#", ""));
+/**
+ * HSL lightness (0–100) used for light/dark sorting and label contrast.
+ * Images without a searchHex fall back to mid lightness so they sort neutrally.
+ */
+const getItemLightness = (item) => {
+    switch (item.kind) {
+        case "color": {
+            return hexLightness(item.hex);
+        }
+        case "gradient": {
+            return (hexLightness(item.from) + hexLightness(item.to)) / 2;
+        }
+        case "image": {
+            return item.searchHex !== undefined &&
+                item.searchHex !== null &&
+                item.searchHex !== ""
+                ? hexLightness(item.searchHex)
+                : 50;
+        }
+        default: {
+            // Exhaustiveness guard: a new ColorPaletteItem kind fails to compile here.
+            const exhaustive = item;
+            return exhaustive;
+        }
+    }
+};
+/**
+ * Stable copy-sort of palette items by lightness. "original" returns the
+ * input array untouched.
+ */
+const sortPaletteItems = (items, sort) => {
+    if (sort === "original") {
+        return items;
+    }
+    const direction = sort === "light-to-dark" ? -1 : 1;
+    return [...items].toSorted((a, b) => direction * (getItemLightness(a) - getItemLightness(b)));
+};
+/**
+ * z-index for a card at a render position. Direction controls which end of
+ * the row stacks on top: "left-first" means the leftmost card overlaps its
+ * neighbour to the right, and vice versa.
+ */
+const stackZIndex = (index, count, direction) => (direction === "left-first" ? count - index : index + 1);
+/**
+ * Selection/render identity for an item: its explicit id, falling back to
+ * its kind plus original (pre-sort) index. Provide explicit ids when
+ * selection must survive item reordering.
+ */
+const getPaletteItemId = (item, index) => item.id ?? `${item.kind}-${index}`;
+/**
+ * Hex an item resolves to for searching and sampling: searchHex when set,
+ * otherwise the fill (gradients fall back to their start stop). Null for
+ * images without a searchHex.
+ */
+const getSampleHex = (item) => {
+    if (item.searchHex !== undefined &&
+        item.searchHex !== null &&
+        item.searchHex !== "") {
+        return normalizeHex(item.searchHex);
+    }
+    switch (item.kind) {
+        case "color": {
+            return normalizeHex(item.hex);
+        }
+        case "gradient": {
+            return normalizeHex(item.from);
+        }
+        case "image": {
+            return null;
+        }
+        default: {
+            // Exhaustiveness guard: a new ColorPaletteItem kind fails to compile here.
+            const exhaustive = item;
+            return exhaustive;
+        }
+    }
+};
+/**
+ * Deep link into the colours search page for an item, or null when the item
+ * has no searchable colour (e.g. an image without a searchHex).
+ *
+ * URL contract of the consuming app's colours page:
+ * `?mode=color&hex=#rrggbb` and `?mode=gradient&gradientStart=…&gradientEnd=…`.
+ */
+const buildSearchHref = (item, basePath = "/colors") => {
+    if (item.kind === "gradient" &&
+        (item.searchHex === undefined ||
+            item.searchHex === null ||
+            item.searchHex === "")) {
+        const start = encodeURIComponent(normalizeHex(item.from));
+        const end = encodeURIComponent(normalizeHex(item.to));
+        return `${basePath}?mode=gradient&gradientStart=${start}&gradientEnd=${end}`;
+    }
+    const hex = getSampleHex(item);
+    if (hex === undefined || hex === null || hex === "") {
+        return null;
+    }
+    return `${basePath}?mode=color&hex=${encodeURIComponent(hex)}`;
+};
+/**
+ * Deep link for sampling a set of items. A single item reuses the
+ * buildSearchHref contract (color/gradient modes); several items deep-link
+ * into the colours page palette mode: `?mode=palette&colors=#a,#b`
+ * (comma-joined, deduped, unsampleable items skipped). Null when nothing
+ * is sampleable.
+ */
+const buildSampleHref = (items, basePath = "/colors") => {
+    const [onlyItem] = items;
+    if (onlyItem && items.length === 1) {
+        return buildSearchHref(onlyItem, basePath);
+    }
+    const hexes = [...new Set(items.flatMap((item) => getSampleHex(item) ?? []))];
+    const [onlyHex] = hexes;
+    if (onlyHex === undefined) {
+        return null;
+    }
+    if (hexes.length === 1) {
+        return buildSearchHref({ hex: onlyHex, kind: "color" }, basePath);
+    }
+    return `${basePath}?mode=palette&colors=${encodeURIComponent(hexes.join(","))}`;
+};
+export { buildSampleHref, buildSearchHref, getItemLightness, getPaletteItemId, getSampleHex, sortPaletteItems, stackZIndex, };

package/dist/compositions/color-palette.d.ts

@@ -0,0 +1,3 @@
+/** biome-ignore-all lint/performance/noBarrelFile: needed for ui package */
+export { ColorPalette, type ColorPaletteLinkProps, type ColorPaletteProps, } from "./color-palette/color-palette-root.js";
+export { buildSampleHref, buildSearchHref, type ColorPaletteItem, getPaletteItemId, getSampleHex, type PaletteDirection, type PaletteSort, sortPaletteItems, } from "./color-palette/palette-sort.js";

package/dist/compositions/color-palette.js

@@ -0,0 +1,3 @@
+/** biome-ignore-all lint/performance/noBarrelFile: needed for ui package */
+export { ColorPalette, } from "./color-palette/color-palette-root.js";
+export { buildSampleHref, buildSearchHref, getPaletteItemId, getSampleHex, sortPaletteItems, } from "./color-palette/palette-sort.js";