@rogieking/figui3 8.9.9 → 8.9.11

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

@@ -0,0 +1,184 @@
+---
+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.
+user-invocable: false
+---
+
+# FigUI3 editor (`fig-editor.js`)
+
+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`.
+
+See also: `figui3` (core), `fig-lab` (`propskit-select` wraps this select).
+
+## Install
+
+```js
+import "@rogieking/figui3/fig.css";
+import "@rogieking/figui3/fig.js";
+import "@rogieking/figui3/fig-editor.css";
+import "@rogieking/figui3/fig-editor.js";
+```
+
+`fig-editor.js` imports `fig.js` and `fig-lab.js`. Still import `fig-editor.css`. Import `fig-lab.css` if lab visuals are needed.
+
+Registered tags:
+
+| Tag | Role |
+|---|---|
+| `fig-select` | Trigger + popup listbox |
+| `fig-select-options` | Scrollable panel (`slot="panel"`), overflow chevrons |
+| `fig-select-option` | Option (`value`, `label`, `selected`, `disabled`) |
+| `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-dropdown` (core): native `<select>`.
+- `fig-select` (this skill): custom listbox.
+- `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`.
+
+| 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 |
+
+Events: `input` / `change` with fill payload in `detail`.
+
+Value shapes:
+
+```txt
+solid   { type, colorSpace, color, alpha, hsv }
+gradient { type, colorSpace, gradient, css }
+image   { type, colorSpace, image }
+video   { type, colorSpace, video }
+webcam  { type, colorSpace, image: { url: snapshot, scaleMode, scale } }
+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 (vanilla)
+
+```html
+<fig-fill-picker mode="solid,tokens">
+  <fig-swatch></fig-swatch>
+  <div slot="mode-tokens" label="Tokens">Token UI</div>
+</fig-fill-picker>
+```
+
+Child `slot="mode-<name>"` plus `<name>` in `mode`. Custom content must dispatch `input` / `change` with `detail` so the picker stores mode data.
+
+### Custom modes (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`
+
+Preview for gradient interpolation (linear or polar hue arc). Playground attrs: `size="small|large"`. Used inside the fill picker gradient UI; can be used standalone with a gradient `value`.
+
+## Maintainer notes
+
+- Implementation: `fig-editor.js`, styles: `fig-editor.css`
+- Do not move fill-picker or select into `fig.js`
+- Nested overlay positioning: keep `popover="manual"` on the select popup
+- Tests: `tests/figui/component-contracts.spec.ts` (ghost variant, sticky separator vs overflow-start)

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

@@ -0,0 +1,46 @@
+# FigUI3 editor API reference
+
+Playground: `/figui3#select`, `/figui3#fill-picker` (Full editor on).
+Rules: `playground/src/lib/attributeRules.ts`.
+
+## `fig-select-option`
+
+Observed: `value`, `disabled`, `selected`, `label`.
+
+- `value` falls back to trimmed `textContent` if the attr is omitted
+- `label` is the closed-trigger string when option content is rich
+- `role="option"`, `aria-selected`, `aria-disabled`
+
+## `fig-select-options`
+
+- Auto `slot="panel"` if missing
+- Unwraps a legacy nested `fig-chooser`
+- First `fig-separator` child gets `borderless`
+- Overflow nav buttons: `data-fig-select-nav`, classes `overflow-start` / `overflow-end`
+- Methods: `syncOverflow()`, `scrollToOption(option, behavior)`
+
+## `fig-select` observed
+
+`value`, `disabled`, `label`, `options`, `position`, `offset`, `closedby`, `open`, `variant`
+
+Position enum (playground):
+
+- `bottom left`, `bottom right`, `top left`, `top right`, `bottom center`, `top center`
+
+Events: `input`, `change`, `optionhover`.
+
+## Fill picker modes
+
+Built-in: `solid`, `gradient`, `image`, `video`, `webcam`.
+
+Gradient spaces: `srgb`, `srgb-linear`, `display-p3`, `oklab`, `oklch`, `hsl`.
+Hue interpolations (oklch/hsl): `shorter`, `longer`, `increasing`, `decreasing`.
+
+`fig-interpolation-swatch` observed: `value` (gradient payload). Size via attr/CSS.
+
+## Color input + picker
+
+When picker is registered, `fig-input-color` / `fig-input-fill` open it on interaction.
+
+- Do not emit `input` from programmatic `value` writes (React loop avoidance)
+- Custom mode JSON: `type` = mode name, remaining keys in payload

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

@@ -0,0 +1,159 @@
+---
+name: fig-lab
+description: >-
+  Guides FigUI3 lab bundle (`fig-lab.js` / `fig-lab.css`): experimental propskit-*
+  property controls, fig-canvas-control, fig-input-angle, 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, reorder lists, or AI
+  chat UIs. Playground: /propskit/lab. APIs are unstable.
+user-invocable: false
+---
+
+# FigUI3 lab (`fig-lab.js`)
+
+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.
+
+## Install
+
+```js
+import "@rogieking/figui3/fig.css";
+import "@rogieking/figui3/fig.js";
+import "@rogieking/figui3/fig-lab.css";
+import "@rogieking/figui3/fig-lab.js";
+```
+
+`propskit-select` prefers `fig-select` (import `fig-editor.js` + `fig-editor.css`). Without editor, it falls back.
+
+`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)
+
+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` (`""` | `large`), `disabled`
+- `default` — reset target (may differ from initial `value`)
+- Right-click **Reset** menu; `resetToDefault()`
+- `propskit-slider` also double-click resets
+- Forward remaining attrs to the inner control
+
+| Tag | Playground | Inner control | Notes |
+|---|---|---|---|
+| `propskit-switch` | `#propskit-switch` | `fig-switch` | `checked`, `default` boolean |
+| `propskit-color` | `#propskit-color` | `fig-input-color` | `alpha` default true |
+| `propskit-gradient` | `#propskit-gradient` | `fig-input-gradient` | `edit`, `mode="handle\|tip"` |
+| `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-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-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 |
+|---|---|
+| Labeled boolean | `propskit-switch` |
+| Labeled continuous number | `propskit-slider` |
+| Labeled exact number | `propskit-number` |
+| Labeled text | `propskit-text` |
+| Labeled discrete list | `propskit-select` (not `fig-dropdown`) |
+| Labeled color / gradient | `propskit-color` / `propskit-gradient` |
+| X/Y | `propskit-position` |
+| Spatial on a canvas | `fig-canvas-control` |
+| Angle | `fig-input-angle` |
+| 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`).
+
+## 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

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

@@ -0,0 +1,67 @@
+# FigUI3 lab API reference
+
+Playground: `/propskit/lab#{id}`. Rules: `playground/src/lib/attributeRules.ts`.
+
+## Propskit reset
+
+- `default` attr stores the reset value
+- `resetToDefault()` on the host
+- Context menu item `reset-default`
+- Slider: double-click also resets
+- Equality helpers treat booleans and JSON objects
+
+## `propskit-select`
+
+Observed: `label`, `direction`, `aria-label`, `options`, `value`.
+
+Uses `fig-select` when `fig-select`, `fig-select-options`, and `fig-select-option` are registered; otherwise a fallback control.
+
+Options attr: JSON array, comma, or newline. Authored `fig-select-options slot="panel"` wins for rich menus.
+
+## `propskit-slider`
+
+Playground attrs: `type` (`range`, `hue`, `delta`, `stepper`, `opacity`), `color`, `label`, `default`, `units`, `elastic` (default true), `size`, `steppers`, `disabled`.
+
+Inner `fig-slider` still needs `min` / `max` / `step` / `value` as forwarded attrs.
+
+## Point JSON shapes
+
+```json
+{"x":50,"y":50}
+{"x":50,"y":50,"radius":60}
+{"x":50,"y":50,"radius":60,"angle":45}
+{"x":10,"y":10,"x2":90,"y2":90}
+```
+
+Color-point combines a color payload with `x`/`y`.
+
+Collapsible point groups: `collapsible` and `open` default true (string booleans).
+
+## `fig-canvas-control`
+
+Observed: `type`, `value`, `color`, `name`, `tooltips`, `disabled`, `drag-surface`, `snapping`.
+
+Parent must be `position: relative` (or similar) so the control can fill it. Playground wraps in an aspect-ratio box.
+
+Types: `point`, `color`, `point-radius`, `point-radius-angle`, `point-point`.
+
+## `fig-input-angle`
+
+Observed include `value`, `precision`, `text`, `min`, `max`, `units`, `dial`, plus `rotations`.
+
+`dial` defaults true. `text="true"` shows the numeric field.
+
+## `fig-reorder`
+
+Observed: `axis`, `handle`, `disabled`.
+
+Event `reorder`: `{ oldIndex, newIndex, item }`.
+
+Nested drag is ignored for sliders, handles, canvas controls, and most propskit spatial controls so inner gestures still work. If a row is still stolen, set `handle` to a drag-affordance selector.
+
+## AI shells
+
+`fig-ai-prompt`, `fig-ai-context`, `fig-chat-message` are empty custom elements (presentation CSS only).
+
+`fig-attachment` observed: `src`, `name`, `value`, `removable`, `disabled`.
+`fig-chat-message`: `from="agent|user"`.