@rogieking/figui3 11.6.0 → 11.6.2

package/.cursor/skills/fig-editor/components.md

@@ -124,10 +124,11 @@ Authored trailing accessory (`/figui3#property/custom-accessory`):
 </fig-property>
 ```
 
-- Attrs: `label`, `leading` (`drag` | `chevron`), `trailing` (`remove` | `add` | `bind`), `show-leading`, `show-trailing`
+- Attrs: `label`, `leading` (`drag` | `chevron`), `trailing` (`remove` | `add` | `bind`), `show-leading`, `show-trailing`, `selected`
 - Slots: `input` (one direct primary control), `label`, `leading`, `trailing`
 - Authored label markup overrides the `label` attribute.
 - Authored accessory slots override generated shortcuts.
+- `selected` and `selected="true"` use the selected background; `selected="false"` does not.
 - Omitted or `"hover"` show attributes use hover visibility; `"false"` never shows the slot; an empty/present attribute always shows it.
 - Generated trailing controls emit bubbling, composed `remove`, `add`, or `bind` events with the slotted control in `detail.input`.
 - Child input events bubble unchanged.
@@ -163,8 +164,10 @@ Reusable ordered palette editor used by `fig-input-palette edit="picker"`.
 />
 ```
 
-- Attrs: `value`, `min`, `max`, `fixed`, `disabled`
+- Attrs: `value`, `min`, `max`, `fixed`, `disabled`, `overflow="fade|visible"`, `show-rows`
 - `max` is unbounded when omitted.
+- Overflow defaults to 6.5 rows with vertical fades; `show-rows` maps to `--fig-palette-editor-overflow-show-rows`, and `visible` shows every row.
+- Additions use shared OKLCH utilities to choose a deterministic, perceptually distinct color that matches the palette.
 - Events: `input` / `change` with the normalized ordered color array in `detail`
 - Uses `fig-reorder` for pointer and keyboard reordering.
 
@@ -180,7 +183,9 @@ Reusable full gradient editor used by the Gradient tab in `fig-fill-picker`.
 />
 ```
 
-- Attrs: `value`, `color-space` (`srgb` | `display-p3`), `disabled`.
+- Attrs: `value`, `color-space` (`srgb` | `display-p3`), `disabled`, `overflow="fade|visible"`, `show-rows`.
+- Stop overflow defaults to 6.5 rows with vertical fades; `show-rows` maps to `--fig-gradient-editor-overflow-show-rows`, and `visible` shows every stop.
+- Stop row and bar-handle selection stay synchronized and scroll the selected row into view. The first stop starts selected. Add Stop inserts midway after the selected row, then selects and focuses the new row.
 - Property: `value` is the normalized gradient config; `cssValue` is the rendered CSS gradient.
 - Property: `pickerAnchor` accepts an element used to anchor nested stop color pickers.
 - Events: `input` / `change` with `{ type: "gradient", gradient, css }`.
@@ -201,7 +206,7 @@ Reusable popup containing one `fig-gradient-editor`. It is the picker opened by
 ></dialog>
 ```
 
-- Attrs: `value`, `color-space`, `disabled`, plus inherited `fig-popup` attributes.
+- Attrs: `value`, `color-space`, `disabled`, `overflow`, `show-rows`, plus inherited `fig-popup` attributes.
 - Events: bubbling `input` / `change` with `{ type: "gradient", gradient, css }`.
 - Create it as `<dialog is="fig-popup-gradient">`.
 
@@ -220,7 +225,7 @@ Reusable palette dialog used by `fig-input-palette edit="picker"`. It extends
 ></dialog>
 ```
 
-- Attrs: `value`, `min`, `max`, `fixed`, `disabled`, plus inherited `fig-popup` attributes.
+- Attrs: `value`, `min`, `max`, `fixed`, `disabled`, `overflow`, `show-rows`, plus inherited `fig-popup` attributes.
 - Property: `value` returns the normalized `{ color, alpha }[]`.
 - Events: bubbling `input` / `change` with the normalized color array in `detail`.
 - Create it as `<dialog is="fig-popup-palette">`, not `<fig-popup-palette>`.

package/.cursor/skills/fig-editor/reference.md

@@ -54,6 +54,7 @@ Events: `input`, `change`, `optionhover`, `optionfocus`.
 - `leading`: `drag` or `chevron`
 - `trailing`: `remove`, `add`, or `bind`
 - `show-leading` / `show-trailing`: omitted or `hover` reveals on hover, `false` hides, and an empty attribute always shows
+- `selected`: present or `true` uses `--figma-color-bg-selected`; `false` leaves the row unselected
 - Authored accessory slots override generated shortcuts.
 - `input` returns the direct `slot="input"` element.
 - Generated labels associate to the input with `aria-labelledby` unless it already has an accessible name.
@@ -81,26 +82,31 @@ Events: `input`, `change`, `optionhover`, `optionfocus`.
 
 ## Palette editor
 
-`fig-palette-editor` observes `value`, `min`, `max`, `fixed`, and `disabled`. An omitted `max` allows unlimited colors.
+`fig-palette-editor` observes `value`, `min`, `max`, `fixed`, `disabled`, `overflow`, and `show-rows`. An omitted `max` allows unlimited colors.
 
 - `value`: JSON array of hex strings or `{ color, alpha }` objects, or comma-separated hex
 - `value` property and `input` / `change` event `detail`: normalized ordered `{ color, alpha }[]`
+- `overflow="fade|visible"`: defaults to a bounded list with vertical fades; `visible` shows every row.
+- `show-rows`: defaults to `6.5` and maps to `--fig-palette-editor-overflow-show-rows`.
 - Rows are direct `fig-reorder` items and support pointer or keyboard reordering.
 
 ## Gradient editor
 
-`fig-gradient-editor` observes `value`, `color-space`, and `disabled`.
+`fig-gradient-editor` observes `value`, `color-space`, `disabled`, `overflow`, and `show-rows`.
 
 - `value` accepts a gradient config or `{ type: "gradient", gradient }` and returns a normalized gradient config.
 - `cssValue` returns the current CSS gradient.
 - `pickerAnchor` anchors nested stop color pickers.
+- `overflow="fade|visible"`: stop rows default to a bounded list with vertical fades; `visible` shows every stop.
+- `show-rows`: defaults to `6.5` and maps to `--fig-gradient-editor-overflow-show-rows`.
 - Bubbling `input` / `change` detail is `{ type: "gradient", gradient, css }`.
 - Interpolation remains locked to sRGB to match the fill picker’s current behavior.
 
 ## Gradient popup
 
 `dialog[is="fig-popup-gradient"]` extends `fig-popup`, owns a
-`fig-gradient-editor`, and observes `value`, `color-space`, and `disabled`.
+`fig-gradient-editor`, and observes `value`, `color-space`, `disabled`,
+`overflow`, and `show-rows`.
 
 - Defaults: `position="bottom left"`, `offset="0 8"`, `viewport-margin="8"`, and `popover="manual"`.
 - Bubbling `input` / `change` detail is `{ type: "gradient", gradient, css }`.
@@ -109,7 +115,7 @@ Events: `input`, `change`, `optionhover`, `optionfocus`.
 
 `dialog[is="fig-popup-palette"]` extends `fig-popup`, owns a
 `fig-palette-editor`, and observes `value`, `min`, `max`, `fixed`, and
-`disabled` in addition to inherited popup attributes.
+`disabled`, `overflow`, and `show-rows` in addition to inherited popup attributes.
 
 - `value` property and bubbling `input` / `change` detail are normalized `{ color, alpha }[]`.
 - Defaults: `position="bottom left"`, `offset="0 8"`, `viewport-margin="8"`, and `popover="manual"`.

package/.cursor/skills/figui3/reference.md

@@ -2,6 +2,14 @@
 
 Public API: `README.md`. React recipes: [components.md](components.md).
 
+## Color utilities
+
+Import pure color math from `@rogieking/figui3/fig-color.js`.
+
+- RGB channels: `0–255`; HSL/HSV percentages: `0–100`; OKLab/OKLCH lightness: `0–1`; hue: normalized degrees.
+- Supports sRGB and true Display-P3 conversion, OKLab distance, hue interpolation, gamut testing, and OKLCH chroma-reduction gamut mapping.
+- Achromatic OKLCH colors use hue `0`.
+
 ## Option string formats
 
 

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [11.6.2]
+
+### Added
+
+- Added shared `fig-color.js` color parsing, conversion, interpolation, contrast, and palette-generation utilities.
+- Added `overflow` and `show-rows` controls for palette and gradient editor stop lists.
+- Added selected-state styling and playground controls for `fig-property`.
+
+### Changed
+
+- Refactored palette and gradient editors to synchronize mounted controls and rows in place, preserving focus, popups, drag state, and controlled-value feedback.
+- Extracted the palette editor into dedicated source and stylesheet modules.
+- Improved palette additions with deterministic, harmonious OKLCH colors.
+- Synchronized gradient stop row and handle selection, scrolled selections into view, and inserted new stops after the selected stop.
+- Expanded editor playground examples, controls, tests, and skill documentation.
+
+### Fixed
+
+- Prevented semantically equivalent editor updates from replacing active controls or interrupting pointer interactions.
+- Kept gradient stop selection singular and stable across adding, removing, reordering, and external updates.
+
+## [11.6.1]
+
+### Changed
+
+- Refined color tips with the tooltip surface color and inset highlight in dark mode.
+
+### Fixed
+
+- Kept recursively nested and portaled popups open while interacting with their owning popup chain.
+- Ensured gradient editors keep only one color-stop handle selected at a time.
+
 ## [11.6.0]
 
 ### Added

package/README.md

@@ -715,7 +715,7 @@ The editable palette is a single tab stop. Enter or Space expands inline mode or
 
 `<fig-property>`
 
-An editor-bundle property row. Supply one control in `slot="input"` and optionally author `slot="label"`, `slot="leading"`, or `slot="trailing"` content. Authored label markup takes precedence over the `label` attribute. The `leading="drag|chevron"` and `trailing="remove|add|bind"` attributes generate common accessories; authored slot content takes precedence. Leading and trailing content appears on hover or focus by default. Set `show-leading="false"` or `show-trailing="false"` to hide it, or add an empty `show-leading` or `show-trailing` attribute to always show it. Generated trailing actions emit bubbling, composed events named `remove`, `add`, or `bind` with the slotted control in `detail.input`. Input events bubble directly from the supplied control.
+An editor-bundle property row. Supply one control in `slot="input"` and optionally author `slot="label"`, `slot="leading"`, or `slot="trailing"` content. Authored label markup takes precedence over the `label` attribute. The `leading="drag|chevron"` and `trailing="remove|add|bind"` attributes generate common accessories; authored slot content takes precedence. Leading and trailing content appears on hover or focus by default. Set `show-leading="false"` or `show-trailing="false"` to hide it, or add an empty `show-leading` or `show-trailing` attribute to always show it. Add `selected` or `selected="true"` for the selected background; `selected="false"` leaves the row unselected. Generated trailing actions emit bubbling, composed events named `remove`, `add`, or `bind` with the slotted control in `detail.input`. Input events bubble directly from the supplied control.
 
 ```html
 <fig-property label="Size" leading="drag" trailing="remove">
@@ -725,11 +725,26 @@ An editor-bundle property row. Supply one control in `slot="input"` and optional
 
 Import `fig-property.js` and `fig-property.css` directly, or use the `fig-editor` bundle, which includes both.
 
+#### Color Utilities
+
+`fig-color.js` is a side-effect-free color math entry point shared by core and editor components.
+
+```js
+import {
+  figHexToOklch,
+  figOklchToHex,
+  figOklabDistance,
+  figMapOklchToGamut,
+} from "@rogieking/figui3/fig-color.js";
+```
+
+RGB channels use `0–255`; HSL/HSV saturation, lightness, and value use `0–100`; OKLab/OKLCH lightness uses `0–1`, chroma is unbounded, and hue uses normalized degrees. Achromatic colors return hue `0`. `figHexToRGB()` returns alpha and `figRGBToHex()` accepts optional alpha; color-space conversion otherwise leaves alpha to the caller. Converters support `colorSpace: "srgb" | "display-p3"`, and `figMapOklchToGamut()` reduces chroma while preserving lightness and hue.
+
 #### Palette Editor
 
 `<fig-palette-editor>`
 
-A reusable editor-bundle component for ordered color arrays. It uses `<fig-reorder>` for pointer and keyboard reordering and emits normalized color arrays from `input` and `change`. It supports `value`, `min`, `max`, `fixed`, and `disabled`; omit `max` for an unlimited number of colors.
+A reusable editor-bundle component for ordered color arrays. It uses `<fig-reorder>` for pointer and keyboard reordering and emits normalized color arrays from `input` and `change`. New colors are selected deterministically in OKLCH to remain perceptually distinct while matching the palette’s lightness and chroma. It supports `value`, `min`, `max`, `fixed`, `disabled`, `overflow="fade|visible"`, and `show-rows`; omit `max` for an unlimited number of colors. Overflow defaults to a bounded list showing 6.5 rows with vertical fades. Set `show-rows` to change that height or use `overflow="visible"` to show every row. `show-rows` maps to `--fig-palette-editor-overflow-show-rows`.
 
 ```html
 <fig-palette-editor value='["#94BD00","#83AD00","#1A632A","#003905"]'></fig-palette-editor>
@@ -740,9 +755,15 @@ A reusable editor-bundle component for ordered color arrays. It uses `<fig-reord
 `<fig-gradient-editor>`
 
 A reusable editor-bundle component for gradient type, direction, stop handles,
-and reorderable stop rows. It supports `value`, `color-space`, and `disabled`;
-its `value` property is the normalized gradient config. Bubbling `input` and
-`change` events include `{ type, gradient, css }`.
+and reorderable stop rows. It supports `value`, `color-space`, `disabled`,
+`overflow="fade|visible"`, and `show-rows`. Stops default to a bounded list
+showing 6.5 rows with vertical fades; `show-rows` maps to
+`--fig-gradient-editor-overflow-show-rows`, and `overflow="visible"` shows every
+stop. Stop row and bar-handle selection stay synchronized and scroll the
+selected row into view. The first stop is selected initially. Selecting another
+row makes Add Stop insert midway between it and the following stop; the new stop
+is selected and focused. Its `value` property is the normalized gradient config.
+Bubbling `input` and `change` events include `{ type, gradient, css }`.
 
 ```html
 <fig-gradient-editor
@@ -757,8 +778,8 @@ its `value` property is the normalized gradient config. Bubbling `input` and
 `<dialog is="fig-popup-gradient">`
 
 A reusable `fig-popup` subclass that owns a `<fig-gradient-editor>`. It
-supports `value`, `color-space`, and `disabled`, plus inherited popup
-positioning. Its bubbling `input` and `change` events include
+supports `value`, `color-space`, `disabled`, `overflow`, and `show-rows`, plus
+inherited popup positioning. Its bubbling `input` and `change` events include
 `{ type, gradient, css }`.
 
 ```html
@@ -1508,7 +1529,10 @@ An anchored floating surface built on `<dialog>` with collision-aware positionin
 </dialog>
 ```
 
-Popups restore focus on close. Escape dismissal is scoped so nested menu and overlay behavior can keep its own keyboard handling.
+Popups restore focus on close. Escape dismissal is scoped so nested menu and
+overlay behavior can keep its own keyboard handling. Anchored popups may be
+rendered in the global overlay root; interacting with a child popup keeps every
+owning ancestor popup open, including recursively nested chains.
 
 ---
 

package/components.css

@@ -7264,8 +7264,10 @@ fig-color-tip {
   height: var(--size);
   aspect-ratio: 1 / 1;
   flex-shrink: 0;
-  background-color: var(--figma-color-bg);
+  background-color: light-dark(var(--figma-color-bg), var(--bg-tooltip));
   border-radius: var(--radius-medium, 0.3125rem);
+  box-shadow: inset 0 0.5px 0 0
+    light-dark(rgba(0, 0, 0, 0.06), rgba(255, 255, 255, 0.1));
   filter: var(--fig-popover-shadow);
 
   &[control="add"],