@rogieking/figui3 8.9.44 → 8.9.46

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

@@ -2,10 +2,10 @@
 name: fig-editor
 description: >-
   Guides FigUI3 editor bundle (`fig-editor.js` / `fig-editor.css`): fig-select,
-  fig-select-options, fig-select-option, fig-fill-picker, and fig-interpolation-swatch.
-  Use when building custom selects, grouped option lists, sticky separators, ghost
-  selects, fill picker dialogs, or interpolation swatches. Playground: /figui3#select
-  and /figui3#fill-picker with the Full editor toggle. Requires fig.js.
+  fig-select-options, fig-select-option, fig-fill-picker, and fig-interpolation-swatch,
+  including React JSX usage. Use when building custom selects, grouped option lists,
+  sticky separators, ghost selects, fill picker dialogs, or interpolation swatches.
+  Requires fig.js.
 user-invocable: false
 ---
 
@@ -13,7 +13,7 @@ user-invocable: false
 
 Custom select and full fill-picker. Not in core `fig.js`.
 
-Canonical examples: `/figui3#select`, `/figui3#fill-picker` (enable **Full editor** in the playground theme menu). Markup: `playground/src/data/figui3Sections.ts`. Attrs: `playground/src/lib/attributeRules.ts`.
+React: [../figui3/react.md](../figui3/react.md). Per-tag JSX: [components.md](components.md). Attrs: [reference.md](reference.md).
 
 See also: `figui3` (core), `fig-lab` (`propskit-select` wraps this select).
 
@@ -38,146 +38,19 @@ Registered tags:
 | `fig-fill-picker` | Full fill editor dialog (solid, gradient, image, video, webcam, custom modes) |
 | `fig-interpolation-swatch` | Gradient interpolation preview swatch |
 
-## `fig-select`
-
-Use this instead of `fig-dropdown` for Figma-style menus (rich options, groups, overflow).
-
-### Markup
-
-Author options in `fig-select-options`, or pass `options` (comma / newline / JSON — same as `fig-options`).
-
-```html
-<fig-select value="center" label="Align">
-  <fig-select-options>
-    <fig-select-option value="left">Left</fig-select-option>
-    <fig-select-option value="center">Center</fig-select-option>
-    <fig-select-option value="right">Right</fig-select-option>
-  </fig-select-options>
-</fig-select>
-
-<fig-select label="Align" value="Center" options="Left,Center,Right"></fig-select>
-```
-
-Rich options: put extra content inside `fig-select-option` and set `label` for the closed trigger text. Use `slot="panel"` on `fig-select-options` when the panel is slotted (playground “verbose” / AI models examples).
-
-```html
-<fig-select value="uuid" label="Version" full>
-  <fig-select-options slot="panel">
-    <fig-select-option value="uuid" label="Current (Version 6)">
-      <strong>Current</strong>
-      <span>Version 6</span>
-    </fig-select-option>
-  </fig-select-options>
-</fig-select>
-```
-
-### Attributes
-
-| Attr | Notes |
-|---|---|
-| `value` | Selected option value |
-| `label` | Closed-state / aria label |
-| `options` | Generated options if no authored `fig-select-option` |
-| `variant` | `ghost` — no border, hover `--figma-color-bg-secondary` |
-| `full` | Stretch width |
-| `disabled` | Presence |
-| `position` | `bottom left` (default), `bottom right`, `top left`, `top right`, `bottom center`, `top center` |
-| `offset`, `closedby`, `open` | Forwarded to internal `fig-popup` |
-
-Same `variant="ghost"` exists on core `fig-dropdown`.
-
-### Groups and sticky separators
-
-```html
-<fig-select-options>
-  <fig-separator label="Darken" sticky></fig-separator>
-  <fig-select-option value="multiply">Multiply</fig-select-option>
-  <fig-separator label="Lighten" sticky></fig-separator>
-  <fig-select-option value="screen">Screen</fig-select-option>
-</fig-select-options>
-```
-
-- First separator in a panel is auto-`borderless`.
-- `sticky` on `fig-separator` pins the label while scrolling.
-- Overflow adds `.overflow-start` / `.overflow-end` on `fig-select-options`. Sticky `top` sits below the overflow chevron (`--fig-vertical-overflow-size`).
-
-Playground: `#select` examples `grouped`, `many-options`; AI models list in `figui3Sections.ts` (`aiModelSelectMarkup()`). Sticky toggle is a playground inspector concern (`?_sticky=1`), not a select host attr.
-
-### Behavior
-
-- Internal popup uses `popover="manual"` (top layer) so the list positions correctly inside `fig-popup variant="popover"` (CSS `filter` containing block).
-- List `min-width` matches the trigger; `max-width` is `min(20rem, calc(100vw - 1rem))`.
-- Overflow: top/bottom chevron buttons, not a native scrollbar.
-- Keyboard: open, arrow, typeahead, Escape.
-- `optionhover` fires on pointer-over with the option value in `event.detail` without changing selection.
-- `input` / `change` on value commit. Do not `stopPropagation` on option click (React light-DOM handlers must run).
-
-### `fig-select` vs `fig-dropdown` vs `propskit-select`
+## `fig-select` vs `fig-dropdown` vs `propskit-select`
 
 - `fig-dropdown` (core): native `<select>`.
-- `fig-select` (this skill): custom listbox.
+- `fig-select` (this skill): custom listbox. Use this for Figma-style menus.
 - `propskit-select` (lab): labeled `fig-field` wrapping `fig-select` (falls back if select is not registered).
 
-## `fig-fill-picker`
-
-Full fill editor. Core `fig-input-color` / `fig-input-fill` auto-open it when registered. Standalone:
-
-```html
-<fig-fill-picker value='{"type":"solid","color":"#FF5733"}'>
-  <fig-swatch></fig-swatch>
-</fig-fill-picker>
-```
-
-Playground: `#fill-picker` — `all-modes`, `solid`, `gradient`, `image`, `video`, `webcam`, `shader` (custom `slot="mode-shader"`).
-
-| Attr | Notes |
-|---|---|
-| `value` | JSON fill object or string |
-| `alpha` | `"true"` default; hide alpha with `"false"` |
-| `mode` | Lock modes: `solid`, `gradient`, `image`, `video`, `webcam`, comma-separated, plus custom names |
-| `disabled` | Presence |
-| `webcam-mode` | `live` (default) or `snapshot`. Webcam tab starts the camera. Capture writes a still and switches to Image |
-| `default-video` | Sample clip URL when Video has no file |
-
-Events: `input` / `change` with fill payload in `detail`. `webcamstream` with `{ stream, deviceId }`. Live camera is `webcamStream` / `releaseWebcam()`, never JSON.
-
-Value shapes:
-
-```txt
-solid   { type, colorSpace, color, alpha, hsv }
-gradient { type, colorSpace, gradient, css }
-image   { type, colorSpace, image: { url, scaleMode, scale } }          // scaleMode includes tile
-video   { type, colorSpace, video: { url, poster, scaleMode, scale, opacity } }  // fill | fit | crop
-webcam  { type, colorSpace, webcam: { live, snapshot, deviceId, scaleMode, scale, opacity } }
-custom  { type: <modeName>, ...payload }
-```
-
-Legacy `{ type: "webcam", image: { url } }` still parses as `webcam.snapshot` for one release. `fig-input-fill` uses the same `webcam` / `video.poster` shapes.
-
-`fig-input-color` expects solid data (`detail.color`, optional `detail.alpha`). Keep legacy `value` / `hex` / `rgba` on color input events.
-
-Do not use `picker` or `picker-anchor` on `fig-input-color`. Forward picker chrome with `picker-*` (e.g. `picker-dialog-position`).
-
-### Custom modes (vanilla)
-
-```html
-<fig-input-fill mode="solid,tokens" value='{"type":"tokens"}'>
-  <div slot="mode-tokens" label="Tokens">Token UI</div>
-</fig-input-fill>
-```
-
-Child `slot="mode-<name>"` plus `<name>` in `mode`. `fig-input-fill` forwards those slots to the inner picker and uses image-style chrome (type label + opacity). Custom content must dispatch `input` / `change` with `detail` so the picker stores mode data.
-
-### Custom modes (React)
+Author options as React children, or pass `options`. Do not `stopPropagation` on option click. `optionhover` is a native listener.
 
-1. Include the mode name in `mode`.
-2. Listen for `modeready`; mount into `e.detail.container`.
-3. Do not reparent React-owned DOM after render.
-4. One React root per container; `unmount()` on host unmount; remove `modeready` listeners.
+## Fill picker
 
-## `fig-interpolation-swatch`
+Core `fig-input-color` / `fig-input-fill` auto-open the picker when registered. Custom modes: `slot="mode-<name>"` on `fig-input-fill`, or React `modeready` → mount into `e.detail.container` (do not reparent).
 
-Preview for gradient interpolation (linear or polar hue arc). Playground attrs: `size="small|large"`. Can be used standalone with a gradient `value`. The fill picker interpolation row is hidden for now and locks to `srgb`.
+Do not use `picker` or `picker-anchor` on `fig-input-color`. Forward picker chrome with `picker-*`.
 
 ## Maintainer notes
 

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

@@ -0,0 +1,134 @@
+# FigUI3 editor components (`fig-editor.js`)
+
+React contract: [../figui3/react.md](../figui3/react.md). Attrs: [reference.md](reference.md).
+
+Install `fig-editor.css` + `fig-editor.js` (pulls in `fig.js` and `fig-lab.js`). Still import `fig-editor.css`. Import `fig-lab.css` if lab visuals are needed.
+
+## `fig-select`
+
+Figma-style listbox. Prefer this over core `fig-dropdown`.
+
+```tsx
+<fig-select value={align} label="Align" full onChange={onChange}>
+  <fig-select-options>
+    <fig-select-option value="left">Left</fig-select-option>
+    <fig-select-option value="center">Center</fig-select-option>
+    <fig-select-option value="right">Right</fig-select-option>
+  </fig-select-options>
+</fig-select>
+```
+
+Data-driven (no authored options):
+
+```tsx
+<fig-select
+  label="Align"
+  value={align}
+  options="Left,Center,Right"
+  onChange={onChange}
+/>
+```
+
+- Attrs: `value`, `label`, `options` (comma / newline / JSON), `variant` (`ghost`), `full`, `disabled`, `position` (`bottom left` default, also `bottom right`, `top left`, `top right`, `bottom center`, `top center`), `offset`, `closedby`, `open`
+- Events: `input` / `change` on commit; `optionhover` with the option value in `detail` (does not change selection). Use a native listener for `optionhover`.
+- Do not `stopPropagation` on option click — React light-DOM handlers must run.
+- Internal popup uses `popover="manual"` so the list works inside `fig-popup variant="popover"`.
+- List `min-width` matches the trigger; `max-width` is `min(20rem, calc(100vw - 1rem))`. Overflow: chevron buttons, not a native scrollbar.
+
+`fig-dropdown` (core) is a native `<select>`. `propskit-select` (lab) wraps this select.
+
+## `fig-select-options`
+
+```tsx
+<fig-select-options slot="panel">
+  <fig-separator label="Darken" sticky />
+  <fig-select-option value="multiply">Multiply</fig-select-option>
+  <fig-separator label="Lighten" sticky />
+  <fig-select-option value="screen">Screen</fig-select-option>
+</fig-select-options>
+```
+
+- Auto `slot="panel"` if missing. Use `slot="panel"` when the panel is slotted (rich / verbose options).
+- First `fig-separator` child is auto-`borderless`. `sticky` pins the label while scrolling.
+- Overflow adds `.overflow-start` / `.overflow-end`. Sticky `top` sits below the overflow chevron (`--fig-vertical-overflow-size`).
+- Methods: `syncOverflow()`, `scrollToOption(option, behavior)`.
+- Options stay in light DOM. Author them as React children.
+
+## `fig-select-option`
+
+```tsx
+<fig-select-option value="uuid" label="Current (Version 6)">
+  <strong>Current</strong>
+  <span>Version 6</span>
+</fig-select-option>
+```
+
+- Attrs: `value` (falls back to trimmed `textContent`), `label` (closed-trigger text when content is rich), `selected`, `disabled`
+- `role="option"`, `aria-selected`, `aria-disabled`
+
+## `fig-fill-picker`
+
+Full fill editor. Core `fig-input-color` / `fig-input-fill` auto-open it when this tag is registered.
+
+```tsx
+<fig-fill-picker
+  value='{"type":"solid","color":"#FF5733"}'
+  onInput={onInput}
+  onChange={onChange}
+>
+  <fig-swatch />
+</fig-fill-picker>
+```
+
+- Attrs: `value` (JSON fill or string), `alpha` (`"true"` default; `"false"` hides), `mode` (`solid`, `gradient`, `image`, `video`, `webcam`, comma-separated, plus custom names), `disabled`, `webcam-mode` (`live` | `snapshot`), `default-video`
+- Events: `input` / `change` with fill payload in `detail`; `webcamstream` with `{ stream, deviceId }`
+- Live camera is `webcamStream` / `releaseWebcam()`, never JSON.
+
+Value shapes:
+
+```txt
+solid    { type, colorSpace, color, alpha, hsv }
+gradient { type, colorSpace, gradient, css }
+image    { type, colorSpace, image: { url, scaleMode, scale } }
+video    { type, colorSpace, video: { url, poster, scaleMode, scale, opacity } }
+webcam   { type, colorSpace, webcam: { live, snapshot, deviceId, scaleMode, scale, opacity } }
+custom   { type: <modeName>, ...payload }
+```
+
+`fig-input-color` expects solid data (`detail.color`, optional `detail.alpha`). Keep legacy `value` / `hex` / `rgba` on color input events.
+
+Do not use `picker` or `picker-anchor` on `fig-input-color`. Forward picker chrome with `picker-*` (e.g. `picker-dialog-position`).
+
+### Custom modes
+
+On `fig-input-fill` (forwards `mode-*` slots to the inner picker, image-style chrome):
+
+```tsx
+<fig-input-fill mode="solid,tokens" value='{"type":"tokens"}'>
+  <div slot="mode-tokens" label="Tokens">
+    Token UI
+  </div>
+</fig-input-fill>
+```
+
+Vanilla: child `slot="mode-<name>"` plus `<name>` in `mode`. Dispatch `input` / `change` with `detail` so the picker stores `{ type: "<name>", …detail }`.
+
+React:
+
+1. Include the mode name in `mode`.
+2. Listen for `modeready`; mount into `e.detail.container`.
+3. Do not reparent React-owned DOM after render.
+4. One React root per container; `unmount()` on host unmount; remove `modeready` listeners.
+
+## `fig-interpolation-swatch`
+
+```tsx
+<fig-interpolation-swatch
+  size="large"
+  value={gradientJson}
+  onInput={onInput}
+/>
+```
+
+- Attrs: `value` (gradient payload), `size` (`small` | `large`)
+- Standalone preview of linear or polar hue interpolation. The fill-picker interpolation row is hidden and locks to `srgb`.

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

@@ -1,7 +1,6 @@
 # FigUI3 editor API reference
 
-Playground: `/figui3#select`, `/figui3#fill-picker` (Full editor on).
-Rules: `playground/src/lib/attributeRules.ts`.
+React recipes: [components.md](components.md).
 
 ## `fig-select-option`
 
@@ -23,7 +22,7 @@ Observed: `value`, `disabled`, `selected`, `label`.
 
 `value`, `disabled`, `label`, `options`, `position`, `offset`, `closedby`, `open`, `variant`
 
-Position enum (playground):
+Position enum:
 
 - `bottom left`, `bottom right`, `top left`, `top right`, `bottom center`, `top center`
 

package/.cursor/skills/fig-lab/SKILL.md

@@ -4,8 +4,8 @@ description: >-
   Guides FigUI3 lab bundle (`fig-lab.js` / `fig-lab.css`): experimental propskit-*
   property controls, fig-canvas-control, fig-input-angle, fig-input-wheel, fig-reorder,
   and AI composer components (fig-ai-prompt, fig-ai-context, fig-chat-message,
-  fig-attachment). Use when building labeled property panels, canvas handles,
-  oscillators, scrubbers, reorder lists, or AI chat UIs. Playground: /propskit/lab.
+  fig-attachment), including React JSX usage. Use when building labeled property
+  panels, canvas handles, oscillators, scrubbers, reorder lists, or AI chat UIs.
   APIs are unstable.
 user-invocable: false
 ---
@@ -14,9 +14,9 @@ user-invocable: false
 
 Experimental components. May change or be removed without notice.
 
-Canonical examples: `/propskit/lab` (`playground/src/data/labSections.ts`).
-Attrs: `playground/src/lib/attributeRules.ts`.
-`/propskit` (raw `fig-field` rows) is the `propkit` skill, not this one.
+React: [../figui3/react.md](../figui3/react.md). Per-tag JSX: [components.md](components.md). Attrs: [reference.md](reference.md).
+
+Raw `fig-field` rows are the `propkit` skill, not this one.
 
 ## Install
 
@@ -31,114 +31,16 @@ import "@rogieking/figui3/fig-lab.js";
 
 `fig-editor.js` already imports `fig-lab.js`; lab **CSS** is still required for lab visuals.
 
-## Catalog
-
-Playground hashes: `/propskit/lab#{id}`.
-
-### Propskit (labeled property controls)
+## Shared propskit
 
-Full-surface `fig-field` wrappers. Prefer these over hand-rolled label+control rows when building lab/property UIs.
-
-Shared:
-
-- `label`, `direction` (`horizontal` default for most), `size` (`""` | `small`; `large` remains an alias for the default), `disabled`
+- `label`, `direction` (`horizontal` default), `size` (`""` | `small`; `large` remains an alias for the default), `disabled`
 - `variant="minimal"` — removes vertical row padding and reveals the field background on hover
 - `default` — reset target (may differ from initial `value`)
-- Right-click **Reset** menu; `resetToDefault()`
+- Right-click **Reset** menu; `resetToDefault()` on a ref
 - `propskit-slider` also double-click resets
 - Forward remaining attrs to the inner control except where a component note says otherwise
 - Rows are large by default; `propskit-group size="small"` applies compact sizing to children without an authored size
 
-| Tag | Playground | Inner control | Notes |
-|---|---|---|---|
-| `propskit-switch` | `#propskit-switch` | `fig-switch` | `checked`, `default` boolean |
-| `propskit-color` | `#propskit-color` | `fig-fill-picker` + `fig-swatch` | Solid swatch, same size as gradient. Clicking the field opens the picker anchored to the host. Focus ring on the field, not the swatch. `alpha` default true |
-| `propskit-fill` | `#propskit-fill` | `fig-fill-picker` + `fig-swatch` | Same chrome as color. Clicking the field opens the picker anchored to the host. Focus ring on the field, not the swatch. Value may be fill JSON or a bare video URL. Forwards `mode-*` slots |
-| `propskit-gradient` | `#propskit-gradient` | `fig-input-gradient` | Default `edit="picker"`. Clicking the field opens the picker anchored to the host. Focus ring on the field, not the gradient. `mode="handle\|tip"` for inline edit |
-| `propskit-select` | `#propskit-select` | `fig-select` | `options` or slotted `fig-select-options` |
-| `propskit-text` | `#propskit-text` | `fig-input-text` | `type`, `readonly` |
-| `propskit-number` | `#propskit-number` | `fig-input-number` | `min`, `max`, `step`, `precision`, `units`, `steppers` |
-| `propskit-slider` | `#propskit-slider` | `fig-slider` | `type` range/hue/delta/stepper/opacity; `elastic` default true |
-| `propskit-wheel` | `#propskit-wheel` | `fig-input-wheel` + optional `fig-input-number` | Labeled scrubber with `label`, `text`, `spin`, `elastic` row stretch, `precision`, `units`, `default`/reset, `size`, and `variant`; units stay on the wrapper/number field and the effective step is applied to the wheel |
-| `propskit-position` | `#propskit-position` | two numbers | `x`, `y`, `units="percent"` |
-| `propskit-color-point` | `#propskit-color-point` | color + position | JSON `value`; `collapsible`, `open` |
-| `propskit-point-radius` | `#propskit-point-radius` | position + radius | JSON `value` |
-| `propskit-point-radius-angle` | `#propskit-point-radius-angle` | + angle | JSON `value` |
-| `propskit-point-point` | `#propskit-point-point` | start/end | `{ x, y, x2, y2 }` |
-| `propskit-group` | `#propskit-group` | group chrome | `name`, `open`, `show-reset` |
-| `propskit-oscillator` | `#oscillator` | waveform editor | JSON `waves`; `edit`, `precision`, `aspect-ratio` |
-
-```html
-<propskit-slider
-  label="Opacity"
-  direction="horizontal"
-  type="opacity"
-  value="100"
-  default="100"
-  min="0"
-  max="100"
-  units="%"
-></propskit-slider>
-
-<propskit-select label="Blend" value="multiply" options="Normal,Multiply,Screen"></propskit-select>
-```
-
-Rich select (requires editor):
-
-```html
-<propskit-select label="Space" value="oklab">
-  <fig-select-options slot="panel">
-    <fig-select-option value="srgb" label="Classic">…</fig-select-option>
-  </fig-select-options>
-</propskit-select>
-```
-
-### Canvas and spatial
-
-| Tag | Playground | Notes |
-|---|---|---|
-| `fig-canvas-control` | `#canvas-control` | Overlay on a positioned parent. `type`: `point` (default), `color`, `point-radius`, `point-radius-angle`, `point-point`. `value` JSON `{x,y,radius?,angle?,x2?,y2?}`. `snapping="modifier\|true\|false"`, `name`, `tooltips`, `color` |
-| `fig-input-angle` | `#angle` | Dial + optional text. `text`, `dial` default true, `rotations`, `min`/`max`/`units` |
-| `fig-input-wheel` | `#input-wheel` | Standalone SVG tick + handle scrubber. Numeric `value`, optional `min`/`max`, `step` default 1, `spin` default true, `disabled` |
-| `fig-reorder` | `#reorder` | `display:contents` wrapper; drag-reorders **direct children**. `axis="vertical\|horizontal"`, `handle` CSS selector when rows contain nested controls. Event: `reorder` `{ oldIndex, newIndex, item }` |
-
-```html
-<div style="position:relative; aspect-ratio:1; width:100%">
-  <fig-canvas-control
-    type="point-radius-angle"
-    name="Position"
-    value='{"x":50,"y":50,"radius":60,"angle":45}'
-    snapping="modifier"
-  ></fig-canvas-control>
-</div>
-```
-
-Omit `handle` on `fig-reorder` to drag whole rows. Set `handle` when children contain sliders/handles so those stay interactive.
-
-### AI composer (presentation)
-
-These are layout shells. Wire behavior yourself.
-
-| Tag | Playground | Notes |
-|---|---|---|
-| `fig-ai-prompt` | `#ai-prompt` | Composer: slot `fig-input-text`, `fig-footer`, buttons, optional `fig-select` |
-| `fig-ai-context` | (with prompt) | Open area above prompt for attachments/status |
-| `fig-chat-message` | `#ai-chat-message` | `from="user\|agent"`. Optional `fig-avatar`, `fig-attachments` |
-| `fig-attachments` / `fig-attachment` | `#ai-attachments` | `src`, `name`, `value`, `removable` default true |
-
-```html
-<fig-chat-message from="user">
-  Create a settings panel.
-  <fig-attachments aria-label="Message attachments">
-    <fig-attachment value="settings" name="settings.png" src="…" removable="false"></fig-attachment>
-  </fig-attachments>
-  <fig-avatar name="Rogie King"></fig-avatar>
-</fig-chat-message>
-<fig-chat-message from="agent">
-  <fig-shimmer><span>Thinking…</span></fig-shimmer>
-</fig-chat-message>
-```
-
 ## Control choice
 
 | Intent | Use |
@@ -157,11 +59,9 @@ These are layout shells. Wire behavior yourself.
 | Section of props | `propskit-group` or core `fig-group` |
 | Reorder rows | `fig-reorder` |
 
-Raw `fig-field` + core control is still valid (see `propkit` skill / `/propskit`).
+Raw `fig-field` + core control is still valid (see `propkit` skill).
 
 ## Maintainer notes
 
 - Implementation: `fig-lab.js`, styles: `fig-lab.css`
 - Keep lab out of `fig.js`
-- Playground loads lab only on `/propskit` and `/propskit/lab`
-- Update `labSections.ts` + `attributeRules.ts` with API changes