@rogieking/figui3 2.29.0 → 2.29.2

package/.cursor/skills/figui3/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: figui3
+description: Guides development and maintenance of the FigUI3 web components library for Figma-style plugin UIs. Applies when adding or modifying `fig-*` custom elements, updating docs/demo pages, adjusting theme tokens, improving accessibility, or debugging component behavior in `fig.js`, `components.css`, `index.html`, and `README.md`.
+user-invocable: false
+---
+
+# FigUI3
+
+A lightweight web components library for Figma UI3-style plugin and widget interfaces.
+
+> IMPORTANT: Prefer the project's native scripts and structure. Use `bun dev` for local docs/demo work and `bun build` for production output.
+
+## Current Project Context
+
+```json
+!`node -e "const p=require('./package.json'); console.log(JSON.stringify({name:p.name,version:p.version,scripts:p.scripts,exports:p.exports},null,2))" 2>/dev/null || echo '{"error":"package.json not found"}'`
+```
+
+The JSON above is the source of truth for package name, build commands, and exported files.
+
+## Principles
+
+1. **Preserve native Web Components patterns.** Keep components framework-agnostic and rooted in custom elements.
+2. **Prefer existing `fig-*` components over one-off markup.** Compose from current primitives before inventing new ones.
+3. **Keep Figma UI3 visual consistency.** Use existing CSS variables and spacing/radius conventions.
+4. **Honor interaction semantics.** Emit `input` while interacting and `change` on committed value changes.
+5. **Treat accessibility as required behavior.** Preserve labels, keyboard support, ARIA attributes, and disabled states.
+
+## React + Vite Integration
+
+### Install and bootstrap in React
+
+- Install package: `npm i @rogieking/figui3` (or `pnpm add` / `bun add`).
+- Import CSS once in app entry (`main.tsx` / `main.jsx`): `import "@rogieking/figui3/fig.css";`
+- Register custom elements before first render. In Vite/React, prefer an explicit bootstrap:
+
+```tsx
+import "@rogieking/figui3/fig.css";
+
+const bootstrap = async () => {
+  // Prevent production tree-shaking from dropping registration side effects.
+  await import("@rogieking/figui3/fig.js");
+  createRoot(document.getElementById("app")!).render(<App />);
+};
+
+bootstrap();
+```
+
+### Vite config guidance
+
+- Standard React Vite config is usually enough:
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+});
+```
+
+- Keep FigUI3 registration import at the top-level app bootstrap (not inside leaf components).
+- If a production build appears to tree-shake element registration, use the explicit dynamic import pattern above.
+
+### React usage rules for web components
+
+- Use DOM attrs on custom elements (`<fig-slider text="true" />`) and read values from `e.target` / `e.detail`.
+- In React, use `class` (not `className`) for all FigUI3 web components (`fig-*` and `<dialog is="fig-...">`) to keep attribute behavior consistent.
+- Prefer refs + `addEventListener` when wiring complex `input`/`change` behavior.
+
+### React + color picker modes (`fig-input-color` / `fig-fill-picker`)
+
+- `fig-input-color` supports custom mode workflows only through `picker="figma"` (internally uses `fig-fill-picker`).
+- The `mode` attribute on `fig-input-color` is pass-through to inner `fig-fill-picker`; mode logic lives in `fig-fill-picker`.
+- `picker-*` attrs on `fig-input-color` are forwarded to `fig-fill-picker` (except `picker-anchor`, which is handled separately).
+  - Example: `picker-dialog-position`, `picker-experimental`, etc.
+- For React custom modes, use `fig-fill-picker` + slot API:
+  - Add a child with `slot="mode-<name>"` (and optional `label`).
+  - Include `<name>` in the `mode` attribute (e.g. `mode="solid,react-demo"`).
+  - Listen for `modeready` and render into `e.detail.container`.
+- Do not reparent React-owned DOM into the picker after render; use the provided `modeready` container as mount target.
+- Keep React lifecycle cleanup explicit for custom mode mounts:
+  - keep one `root` per mode container
+  - call `root.unmount()` when the host component unmounts
+  - remove `modeready` listeners in cleanup to avoid duplicate mounts
+- Custom mode content must dispatch `input` / `change` with `detail` payload so picker can store mode data and propagate events.
+- Preserve value shape expectations:
+  - `fig-input-color` expects solid color data (`detail.color`, optional `detail.alpha`) from the picker.
+  - `fig-fill-picker` custom modes use JSON with `type` set to mode name and remaining data in payload.
+- Keep `picker-anchor` behavior explicit in React:
+  - `picker-anchor="self"` anchors to the color input element itself.
+  - Selector values anchor to another DOM element (resolved via `document.querySelector`).
+
+## Experimental Attribute Guidance
+
+- Use `experimental` as a feature-flag string for opt-in behavior. Treat it as progressive enhancement, not guaranteed baseline behavior.
+- Prefer `experimental="modern"` when enabling modern customizable select/picker UI behavior.
+- Keep usage explicit on the component that needs it (for example `fig-dropdown`, `fig-fill-picker`, `fig-input-fill`, `fig-input-color`).
+- Preserve pass-through behavior:
+  - `fig-input-color` and `fig-input-fill` forward experimental-related picker settings into internal `fig-fill-picker` usage.
+  - Avoid adding hidden implicit defaults that enable experimental behavior globally.
+- Backward-compat rule:
+  - Do not reintroduce `variant="neue"` for dropdown experimental behavior.
+  - Keep `variant="neue"` handling only where it is still intentionally supported (for example slider visuals).
+- Documentation rule: any new experimental token must be documented with activation syntax, intended scope, and fallback behavior in demos + README + changelog.
+
+## Critical Rules
+
+### Overlay Components (`fig-dialog`, `fig-popup`)
+
+- Choose the overlay primitive intentionally:
+  - **`<dialog is="fig-dialog">`** for modal/light-dismiss dialog workflows.
+  - **`<dialog is="fig-popup">`** for anchored floating surfaces (menus, contextual panels, nested popups).
+- Keep overlay semantics stable:
+  - `fig-dialog` should remain dialog-first (title/header/footer patterns, modal semantics).
+  - `fig-popup` should remain anchor/position-first (offset, collision handling, viewport margins).
+- Preserve drag and positioning behavior on both `fig-dialog` and `fig-popup`; do not regress manual placement rules.
+- For popup chains, maintain containment and dismissal logic across descendant popups.
+- Document any overlay behavior change in demos and changelog with a concrete before/after note.
+
+### Component Architecture
+
+- Extend `HTMLElement` and implement lifecycle cleanup in `disconnectedCallback`.
+- Use `observedAttributes` + `attributeChangedCallback` for attribute-driven reactivity.
+- Keep attribute names and behavior backward-compatible unless explicitly doing a breaking change.
+- Support `disabled` behavior wherever interaction is possible.
+- Avoid introducing framework-specific assumptions in component internals.
+
+### Events and Data Contracts
+
+- Emit standard `input` and `change` events for form-like controls.
+- Put rich payloads in `event.detail` when needed; keep names stable.
+- Do not silently change event payload shape for existing components.
+- When adding new events, document trigger timing and payload fields.
+
+### Styling and Theming
+
+- Reuse established design tokens and CSS variables before adding new ones.
+- Keep light/dark compatibility working with `color-scheme` and current token strategy.
+- Avoid ad-hoc hardcoded colors when semantic tokens already exist.
+- Preserve current sizing, spacing, and radius rhythm unless intentionally refactoring system-wide.
+
+### Documentation and Demos
+
+- Update `README.md` component docs when public API or behavior changes.
+- Update demo pages (`index.html` and `propkit.html` where relevant) for visible behavior changes.
+- Prefer realistic examples that mirror plugin/property panel usage.
+- If introducing an experimental feature, document activation and fallback behavior clearly.
+
+### Compatibility and Safety
+
+- Keep browser support expectations aligned with current README claims.
+- Use progressive enhancement for bleeding-edge CSS features.
+- Avoid regressions in existing attributes, defaults, and emitted events.
+
+### Color Picker Mode Extensibility
+
+- Treat custom modes as a `fig-fill-picker` concern, not a standalone `fig-input-color` concern.
+- When adding a new mode, update demos/docs with both:
+  - vanilla slot usage (`slot="mode-*"`)
+  - React `modeready` usage
+- Do not emit `input` from programmatic attribute writes (`value` updates); preserve current loop-avoidance behavior for React.
+
+## Key Patterns
+
+```html
+<!-- Modal/dialog content container -->
+<dialog is="fig-dialog" drag="true" handle="fig-header">
+  <fig-header>
+    Dialog Title
+    <fig-button variant="ghost" icon close-dialog aria-label="Close dialog">
+      <span class="fig-mask-icon" style="--icon: var(--icon-close)"></span>
+    </fig-button>
+  </fig-header>
+  <div>Dialog body</div>
+</dialog>
+
+<!-- Anchored popup surface -->
+<dialog is="fig-popup" anchor="#trigger" position="bottom left" offset="8 8">
+  <div>Popup content</div>
+</dialog>
+```
+
+```js
+// Event contract pattern: continuous + committed updates.
+this.dispatchEvent(new CustomEvent("input", { detail, bubbles: true }));
+this.dispatchEvent(new CustomEvent("change", { detail, bubbles: true }));
+
+// Attribute-driven updates.
+static get observedAttributes() { return ["value", "disabled"]; }
+attributeChangedCallback(name, oldValue, newValue) {
+  if (oldValue === newValue) return;
+  // sync internal UI state
+}
+```
+
+```txt
+Event contract quick map:
+- fig-slider: input/change -> current value on e.target.value
+- fig-input-color: input/change -> value on e.target.value, structured color via e.detail (when available)
+- fig-input-fill / fig-fill-picker: input/change -> fill payload in e.detail
+```
+
+```html
+<!-- Typical field composition -->
+<fig-field direction="horizontal">
+  <label>Opacity</label>
+  <fig-slider value="75" min="0" max="100" text="true" units="%"></fig-slider>
+</fig-field>
+```
+
+## `fig-popup` vs `fig-dialog`
+
+- **Use `fig-dialog` when the UI is a dialog.**
+  - Best for modal or primary task flows.
+  - Works well with explicit dialog structure and close policies.
+- **Use `fig-popup` when you need low-level floating control.**
+  - Best for anchored contextual surfaces and advanced positioning behavior.
+  - Prefer this when you need explicit anchor/position/offset/viewport tuning.
+
+Rule of thumb: `fig-dialog` = dialog UX, `fig-popup` = popup primitive.
+
+## Workflow
+
+1. **Read existing implementation first.** Check `fig.js`, `components.css`, and related demo usage before editing.
+2. **Confirm API surface impact.** Identify affected attributes, events, and slots.
+3. **Implement with compatibility in mind.** Preserve defaults and old usage unless explicitly changed.
+4. **Update docs/demo in same pass.** Keep examples and behavior synchronized.
+5. **Run project checks.** Use `bun dev` for interactive verification and `bun build` for output sanity.
+6. **Verify accessibility and theming.** Check keyboard flow, labels, disabled states, and both light/dark appearance.
+
+## Release-Ready Checklist
+
+- Validate in a production build (`bun build`) and confirm custom elements are registered at runtime.
+- Verify `input` vs `change` behavior for touched controls in both vanilla usage and React integration.
+- Verify light/dark themes and keyboard navigation for any changed component.
+- Verify overlay behavior (`fig-dialog`, `fig-popup`) including close/dismiss and drag behavior when applicable.
+- Update `README.md`, demos, and `CHANGELOG.md` for any public API or behavior change.
+
+## Quick Reference
+
+```bash
+# Start docs/demo server
+bun dev
+
+# Build distributable files
+bun build
+```
+
+## Primary Files
+
+- `fig.js` - component implementations and behavior
+- `components.css` - component-level styling and states
+- `base.css` - foundational styles and variables
+- `index.html` - main interactive docs/demo
+- `README.md` - public API and usage documentation
+- `CHANGELOG.md` - release history and migration notes

package/.cursor/skills/propkit/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: propkit
+description: Guides creation and refinement of Figma-style property panel patterns ("PropKit") using FigUI3 components. Applies when building or modifying property fields in `propkit.html`, generating consistent field prompts, composing horizontal `fig-field` rows, or tuning panel UX for controls like image, color, fill, slider, switch, dropdown, segmented control, easing, and angle.
+user-invocable: false
+---
+
+# PropKit
+
+Patterns for composing clean, production-ready Figma property panels with FigUI3.
+
+> IMPORTANT: Favor composition and consistency over custom one-off controls. Build panels from existing `fig-*` elements first.
+
+## Current Project Context
+
+```json
+!`node -e "const fs=require('fs'); const ok=fs.existsSync('propkit.html'); console.log(JSON.stringify({propkit:ok, example:'horizontal fig-field + label + fig-* control'},null,2))" 2>/dev/null || echo '{"error":"context unavailable"}'`
+```
+
+## Principles
+
+1. **Use horizontal property rows by default.** PropKit fields are primarily `fig-field direction="horizontal"`.
+2. **One clear label per control.** Keep labels concise and aligned with Figma property language.
+3. **Prefer native FigUI3 controls.** Use `fig-input-fill`, `fig-slider`, `fig-dropdown`, `fig-switch`, etc.
+4. **Use realistic panel widths and spacing.** Match the property panel feel (`~240px` panel blocks in demos).
+5. **Keep prompts and examples deterministic.** Prompt text should describe exact structure and key attributes.
+
+## React + Vite PropKit Usage
+
+### Include FigUI3 in React projects
+
+- Import once in app bootstrap:
+  - `import "@rogieking/figui3/fig.css";`
+  - `await import("@rogieking/figui3/fig.js");`
+- Register components before first React render to avoid undefined custom elements.
+- Keep this setup in entry files (`main.tsx` / `main.jsx`), not scattered across feature components.
+
+### Vite setup and tree-shaking behavior
+
+- Base Vite React config is sufficient in most cases:
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+});
+```
+
+- In production, FigUI3 side-effect registration can be tree-shaken if only imported for side effects.
+- Preferred pattern (from `webgpu-effects`) is explicit async bootstrap:
+
+```tsx
+import "@rogieking/figui3/fig.css";
+
+const bootstrap = async () => {
+  await import("@rogieking/figui3/fig.js");
+  createRoot(document.getElementById("app")!).render(<App />);
+};
+
+bootstrap();
+```
+
+### React composition conventions for PropKit rows
+
+- Continue using canonical row shape in JSX:
+  - `<fig-field direction="horizontal">` + `<label>` + one primary `fig-*` control.
+- For customized built-ins in React (`<dialog is="fig-popup">` / `<dialog is="fig-dialog">`), use `class`, not `className`.
+- Use refs and native event listeners (`input`, `change`) for reliable control updates.
+
+## Critical Rules
+
+### Field Composition
+
+- Default pattern: label + single primary control inside one horizontal `fig-field`.
+- Keep control-specific options on the component itself (not hidden wrapper logic).
+- Use `full` where property controls should stretch within row constraints.
+- Avoid mixing unrelated controls in a single field row unless intentionally grouped.
+
+### Prompt Generation Style
+
+- Write prompts as imperative build instructions.
+- Include field direction, control tag, and meaningful attrs.
+- Prefer short explicit phrasing over vague prose.
+- Keep wording consistent:
+  - `Use a horizontal fig-field...`
+  - `With a label of ...`
+- Include concrete defaults when relevant (value, min/max, step, units, mode, variant) so generated fields are deterministic.
+- Avoid placeholder-only prompts for numeric controls; always specify range semantics.
+
+### Control Guidance
+
+- **Image:** prefer `fig-image` with `upload`, `fit`, and `aspect-ratio` where needed.
+- **Color:** use `fig-input-color` with `text="true"` and optional `alpha`.
+- **Fill:** use `fig-input-fill` for multi-mode fills; keep value JSON valid.
+- **Slider:** choose proper type (`range`, `opacity`, `hue`, `stepper`, `delta`) and include units/transform intentionally.
+- **Dropdown:** use `fig-dropdown`; include sensible default options.
+- **Boolean:** use `fig-switch`; avoid using dropdowns for true/false.
+- **Discrete choices:** use `fig-segmented-control` + `fig-segment`.
+- **Motion easing:** use `fig-easing-curve` with/without presets depending on context.
+- **Angle:** use `fig-input-angle` with `text="true"` for precision workflows.
+
+### Slider Types and Variants
+
+- Default to `type="range"` for generic numeric properties (opacity %, size, spacing, intensity).
+- Use `type="opacity"` when color context is needed (set `color` and usually `units="%"`).
+- Use `type="hue"` only for hue selection workflows.
+- Use `type="stepper"` for discrete snap points (include a `datalist` with valid stops).
+- Use `type="delta"` for offset/relative adjustments around a neutral point (typically include `default`, and often symmetric min/max).
+- Prefer `text="true"` for precision-critical properties; omit it for compact/simplified rows.
+- Use `transform` when internal value scale differs from UI display (example: internal `0..1`, display `0..100%`).
+- Variants:
+  - Default variant for most property panels.
+  - `variant="minimal"` for visually quieter contexts.
+  - `variant="neue"` only where explicitly requested for that panel's style.
+- Always set explicit `min`, `max`, and `step` (and `units` where applicable) to keep behavior predictable.
+
+### Control Selection Heuristics
+
+- Use `fig-slider` for scrub-friendly continuous values (opacity, intensity, scale, blur amount).
+- Use `fig-input-number` for precise direct entry (sizes, coordinates, exact typed values).
+- Use slider + text (`text="true"`) when users need both quick scrubbing and precise adjustment.
+- Use `fig-segmented-control` for small discrete sets (2-5 fixed options).
+- Use `fig-dropdown` for larger or less frequently switched option sets.
+- Use `fig-switch` for binary state, never slider/dropdown for pure on/off.
+
+### UX Consistency
+
+- Keep panel patterns visually consistent across sections.
+- Preserve theme behavior (light/dark) and avoid non-token color overrides.
+- Ensure labels and controls remain keyboard and screen-reader usable.
+
+## Key Patterns
+
+```html
+<!-- Canonical PropKit row -->
+<fig-field direction="horizontal">
+  <label>Opacity</label>
+  <fig-slider value="75" min="0" max="100" text="true" units="%" full></fig-slider>
+</fig-field>
+```
+
+```html
+<!-- Non-horizontal (stacked/default column) field -->
+<fig-field>
+  <label>Opacity</label>
+  <fig-slider value="75" min="0" max="100" text="true" units="%"></fig-slider>
+</fig-field>
+```
+
+```html
+<!-- Fill + blend pair -->
+<fig-field direction="horizontal">
+  <label>Fill</label>
+  <fig-input-fill value='{"type":"solid","color":"#667eea"}' experimental="modern"></fig-input-fill>
+</fig-field>
+<fig-field direction="horizontal">
+  <label>Blend</label>
+  <fig-dropdown full experimental="modern">
+    <option selected>Normal</option>
+    <option>Multiply</option>
+  </fig-dropdown>
+</fig-field>
+```
+
+```txt
+Prompt pattern:
+Use a horizontal fig-field, with a fig-slider, min=0 max=100 text=true units=%. With a label of Opacity.
+```
+
+```html
+<!-- Slider type/variant examples -->
+<fig-field direction="horizontal">
+  <label>Opacity</label>
+  <fig-slider type="opacity" value="0.75" color="#0D99FF" units="%" text="true" full></fig-slider>
+</fig-field>
+<fig-field direction="horizontal">
+  <label>Hue</label>
+  <fig-slider type="hue" value="180" text="true" variant="minimal" full></fig-slider>
+</fig-field>
+<fig-field direction="horizontal">
+  <label>Offset</label>
+  <fig-slider type="delta" value="0" default="0" min="-5" max="5" step="0.25" text="true" full></fig-slider>
+</fig-field>
+```
+
+## Workflow
+
+1. **Identify property intent.** Determine if control is boolean, discrete choice, continuous numeric, color/fill, media, or motion.
+2. **Pick the canonical FigUI3 control.** Avoid custom alternatives unless required.
+3. **Compose row structure.** Use horizontal `fig-field`, then label + control.
+4. **Set defaults and attrs explicitly.** Include values/ranges/units so behavior is deterministic.
+5. **Verify panel consistency.** Check row spacing, width, and theme parity against existing PropKit sections.
+6. **Validate events and interactions.** Ensure controls emit usable `input`/`change` and behave well in keyboard workflows.
+
+## Delivery Checklist
+
+- Confirm prompts include all behavior-critical attrs (`value`, `min`, `max`, `step`, `units`, `type`, `variant` as needed).
+- Confirm control choice matches intent (continuous vs discrete vs boolean vs exact numeric entry).
+- Verify row density and panel width feel consistent with existing PropKit sections.
+- Verify keyboard navigation and label association for every field row.
+- Verify changes in `propkit.html` still mirror recommended patterns in this skill.
+
+## Quick Reference
+
+```txt
+Common PropKit controls:
+- fig-image
+- fig-input-color
+- fig-input-fill
+- fig-slider
+- fig-switch
+- fig-dropdown
+- fig-segmented-control
+- fig-easing-curve
+- fig-input-angle
+```
+
+## Primary Files
+
+- `propkit.html` - canonical PropKit examples and prompt-copy behavior
+- `fig.js` - control behavior and emitted events
+- `components.css` - visual treatment and layout constraints
+- `README.md` - component API details and usage

package/components.css

@@ -1447,7 +1447,7 @@ fig-3d-rotate {
   }
 
   > fig-input-number {
-    flex: 1 0 4rem;
+    flex: 1 0 3rem;
   }
 
   .fig-3d-rotate-container {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rogieking/figui3",
-  "version": "2.29.0",
+  "version": "2.29.2",
   "description": "A lightweight web components library for building Figma plugin and widget UIs with native look and feel",
   "author": "Rogie King",
   "license": "MIT",
@@ -12,7 +12,8 @@
     "./fig.js": "./fig.js",
     "./fig.css": "./fig.css",
     "./base.css": "./base.css",
-    "./components.css": "./components.css"
+    "./components.css": "./components.css",
+    "./propkit.html": "./propkit.html"
   },
   "files": [
     "fig.js",
@@ -20,7 +21,9 @@
     "base.css",
     "components.css",
     "index.html",
+    "propkit.html",
     "dist/",
+    ".cursor/skills/",
     "README.md",
     "LICENSE"
   ],