@rogieking/figui3 8.9.44 → 8.9.45

package/.cursor/skills/figui3/react.md

@@ -0,0 +1,263 @@
+# React + FigUI3
+
+FigUI3 is web components. Use the tags in JSX. There is no React wrapper package.
+
+Shared by `figui3`, `fig-editor`, and `fig-lab`. Per-tag recipes: [components.md](components.md).
+
+## Bootstrap
+
+Register CSS + JS before the first render. Dynamic `import()` keeps bundlers from tree-shaking registration.
+
+```tsx
+import { createRoot } from "react-dom/client";
+import "@rogieking/figui3/fig.css";
+
+const bootstrap = async () => {
+  await import("@rogieking/figui3/fig.js");
+  createRoot(document.getElementById("app")!).render(<App />);
+};
+
+bootstrap();
+```
+
+Add editor and/or lab the same way, before render:
+
+```tsx
+import "@rogieking/figui3/fig-editor.css";
+await import("@rogieking/figui3/fig-editor.js");
+
+import "@rogieking/figui3/fig-lab.css";
+await import("@rogieking/figui3/fig-lab.js");
+```
+
+SSR (Next/Remix/Astro): import the JS only on the client.
+
+## JSX types
+
+```ts
+import "react";
+
+type FigAttrs = React.DetailedHTMLProps<
+  React.HTMLAttributes<HTMLElement>,
+  HTMLElement
+> & { [key: string]: unknown };
+
+type FigTag =
+  | "fig-3d-rotate"
+  | "fig-ai-context"
+  | "fig-ai-prompt"
+  | "fig-attachment"
+  | "fig-attachments"
+  | "fig-avatar"
+  | "fig-button"
+  | "fig-button-combo"
+  | "fig-canvas-control"
+  | "fig-card"
+  | "fig-chat-message"
+  | "fig-checkbox"
+  | "fig-chit"
+  | "fig-choice"
+  | "fig-chooser"
+  | "fig-color-tip"
+  | "fig-combo-input"
+  | "fig-content"
+  | "fig-dropdown"
+  | "fig-easing-curve"
+  | "fig-field"
+  | "fig-fill-picker"
+  | "fig-footer"
+  | "fig-group"
+  | "fig-handle"
+  | "fig-header"
+  | "fig-icon"
+  | "fig-image"
+  | "fig-input-angle"
+  | "fig-input-color"
+  | "fig-input-combo"
+  | "fig-input-file"
+  | "fig-input-fill"
+  | "fig-input-gradient"
+  | "fig-input-number"
+  | "fig-input-palette"
+  | "fig-input-text"
+  | "fig-input-wheel"
+  | "fig-interpolation-swatch"
+  | "fig-joystick"
+  | "fig-layer"
+  | "fig-media"
+  | "fig-media-controls"
+  | "fig-menu"
+  | "fig-menu-item"
+  | "fig-menu-separator"
+  | "fig-options"
+  | "fig-origin-grid"
+  | "fig-preview"
+  | "fig-radio"
+  | "fig-reorder"
+  | "fig-segment"
+  | "fig-segmented-control"
+  | "fig-select"
+  | "fig-select-option"
+  | "fig-select-options"
+  | "fig-separator"
+  | "fig-shimmer"
+  | "fig-skeleton"
+  | "fig-slider"
+  | "fig-spinner"
+  | "fig-swatch"
+  | "fig-switch"
+  | "fig-tab"
+  | "fig-tab-content"
+  | "fig-tabs"
+  | "fig-tooltip"
+  | "fig-truncate"
+  | "fig-video"
+  | "propskit-color"
+  | "propskit-color-point"
+  | "propskit-fill"
+  | "propskit-gradient"
+  | "propskit-group"
+  | "propskit-number"
+  | "propskit-oscillator"
+  | "propskit-point-point"
+  | "propskit-point-radius"
+  | "propskit-point-radius-angle"
+  | "propskit-position"
+  | "propskit-select"
+  | "propskit-slider"
+  | "propskit-switch"
+  | "propskit-text"
+  | "propskit-wheel";
+
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements
+      extends Record<FigTag, FigAttrs> {
+      dialog: React.DetailedHTMLProps<
+        React.DialogHTMLAttributes<HTMLDialogElement>,
+        HTMLDialogElement
+      > & { is?: string; [key: string]: unknown };
+    }
+  }
+}
+```
+
+## Host JSX
+
+Render the custom elements as tags. Children are React nodes (`key` on lists). `className` works on `fig-*`, `propskit-*`, and `<dialog is="fig-…">`.
+
+```tsx
+<fig-field direction="horizontal">
+  <label>Opacity</label>
+  <fig-slider
+    value={String(opacity)}
+    min="0"
+    max="100"
+    text="true"
+    units="%"
+    full
+    onInput={onInput}
+    onChange={onChange}
+  />
+</fig-field>
+```
+
+## Attributes
+
+- Strings: `text="true"`, `variant="ghost"`, `value={String(n)}`.
+- Presence: `icon`, `full`, `compact`, `disabled` as boolean props; unset with `undefined`.
+- Checked: `checked={on ? "true" : undefined}` — never `checked={false}`.
+- Native dialog open: `open={open ? true : undefined}`.
+- Optional flags / `data-*`: omit with `undefined`.
+
+Passing `value` / `checked` as JSX props on re-render is OK. Components do not emit `input` from programmatic writes and ignore value writes during drag.
+
+## Events
+
+Use React handlers:
+
+- `onClick` — `fig-button` and other clickable hosts
+- `onInput` — live (`fig-switch`, `fig-slider`, number/color/text)
+- `onChange` — commit (`fig-options`, `fig-dropdown`, often paired with `onInput`)
+
+Read order:
+
+1. `event.detail` (`.checked`, `.value`, or the detail payload)
+2. `event.currentTarget.value` / `.checked`
+3. `event.target.value`
+
+```tsx
+function readValue(event: Event) {
+  const custom = event as CustomEvent<{ checked?: boolean; value?: unknown }>;
+  const host = event.currentTarget as HTMLElement & {
+    value?: unknown;
+    checked?: boolean;
+  };
+  if (typeof custom.detail?.checked === "boolean") return custom.detail.checked;
+  if (custom.detail?.value !== undefined) return custom.detail.value;
+  if (custom.detail !== undefined && custom.detail !== null) return custom.detail;
+  return host.value ?? host.checked;
+}
+```
+
+Native `addEventListener` only when React does not map the event: dialog `close` / `cancel`, delegated host clicks, imperative APIs.
+
+Common events: `input`, `change`, `loaded`, `optionhover`, `reorder`, `remove`, `modeready`, `webcamstream`, `close`.
+
+## Customized built-ins
+
+Do not use `<fig-dialog>`, `<fig-popup>`, or `<fig-toast>`. Use `<dialog is="…">`.
+
+```tsx
+const buttonRef = useRef<HTMLElement>(null);
+const popupRef = useRef<HTMLDialogElement>(null);
+
+useEffect(() => {
+  const popup = popupRef.current;
+  if (!popup) return;
+  (popup as HTMLDialogElement & { anchor?: Element | null }).anchor =
+    buttonRef.current;
+  const onClose = () => setOpen(false);
+  popup.addEventListener("close", onClose);
+  return () => popup.removeEventListener("close", onClose);
+}, []);
+
+<dialog
+  ref={popupRef}
+  is="fig-popup"
+  variant="popover"
+  position="bottom"
+  offset="0 8"
+  className="preferences-popup"
+  open={open ? true : undefined}
+>
+  <fig-header>Preferences</fig-header>
+  <fig-content>…</fig-content>
+</dialog>
+```
+
+Set `anchor` as an element on the ref after mount (selector strings also work).
+
+## Imperative refs
+
+`useRef<HTMLElement>(null)` on hosts. Tooltips:
+
+```tsx
+tooltip.text = "Copied";
+tooltip.showPopup?.();
+tooltip.hidePopup?.();
+```
+
+Toasts: `toast.showToast()`. Lab reset: `host.resetToDefault()`.
+
+## Light DOM
+
+React owns child nodes. Components slot; they do not relocate children.
+
+- `fig-menu` items; trigger gets `slot="trigger"`
+- `fig-select-options slot="panel"`
+- `fig-tabs` / `fig-chooser` children
+- media `slot="overlay"`
+- fill custom `slot="mode-*"`
+
+Do not `innerHTML` a tree React rendered. Do not reparent nodes React created. Children may arrive after `connectedCallback`; hosts already watch for that.

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

@@ -1,7 +1,6 @@
 # FigUI3 core API reference
 
-Source of truth for live attrs: `playground/src/lib/attributeRules.ts` and `README.md`.
-Playground: `/figui3#{section}`.
+Public API: `README.md`. React recipes: [components.md](components.md).
 
 ## Option string formats
 
@@ -84,8 +83,8 @@ import "@rogieking/figui3/fig-layer.css";
 import "@rogieking/figui3/fig-layer.js";
 ```
 
-Attrs: `open`, `visible`, `disabled`. Markup: child `.fig-layer-row` plus nested `fig-layer`. Events: `openchange`, `visibilitychange`. Playground: `/figui3#layer` (behind Full editor).
+Attrs: `open`, `visible`, `disabled`. Markup: child `.fig-layer-row` plus nested `fig-layer`. Events: `openchange`, `visibilitychange`.
 
 ## Native elements
 
-`/figui3` also demos styled native `button`, `select`, `input`, `textarea`, `checkbox`, `.switch`, `radio`, `color`, `progress`, `fieldset`, `details`, `hr` under group “Native elements”. Use these when a custom element is unnecessary.
+Styled native `button`, `select`, `input`, `textarea`, `checkbox`, `.switch`, `radio`, `color`, `progress`, `fieldset`, `details`, `hr` when a custom element is unnecessary.

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

@@ -1,10 +1,9 @@
 ---
 name: propkit
 description: >-
-  Guides Figma-style property panel composition in the /propskit playground using
-  fig-field rows and FigUI3 controls. Use when building or editing
-  playground/src/data/sections.ts, generating field prompts, or choosing between
-  raw fig-* rows and propskit-* wrappers (fig-lab).
+  Guides Figma-style property panel composition using fig-field rows and FigUI3
+  controls, including React JSX. Use when building labeled property panels or
+  choosing between raw fig-* rows and propskit-* wrappers (fig-lab).
 user-invocable: false
 ---
 
@@ -12,54 +11,47 @@ user-invocable: false
 
 Patterns for Figma property panels. Two layers:
 
-| Surface | Route | What to use |
-|---|---|---|
-| **PropsKit playground** | `/propskit` | Horizontal `fig-field` + core `fig-*` |
-| **Lab wrappers** | `/propskit/lab` | `propskit-*` (see `fig-lab` skill) |
+| Surface | What to use |
+|---|---|
+| **Core rows** | Horizontal `fig-field` + core `fig-*` |
+| **Lab wrappers** | `propskit-*` (see `fig-lab` skill) |
 
-Canonical `/propskit` examples: `playground/src/data/sections.ts`.
-Core control APIs: `figui3` skill. Select/fill picker: `fig-editor`. Labeled wrappers: `fig-lab`.
+Core tags: `figui3` skill + [../figui3/components.md](../figui3/components.md). React: [../figui3/react.md](../figui3/react.md). Select/fill picker: `fig-editor`. Labeled wrappers: `fig-lab`.
 
 ## Principles
 
 1. Default to horizontal `fig-field` rows.
 2. One concise label per control.
 3. For new labeled property controls in lab, prefer `propskit-*` over duplicating field chrome.
-4. In `/propskit` demos, keep composing from `fig-*` so examples stay core-only unless the section needs lab.
-5. Panel width ~240px. Match existing section density.
-
-## React bootstrap
-
-```tsx
-import "@rogieking/figui3/fig.css";
-
-const bootstrap = async () => {
-  await import("@rogieking/figui3/fig.js");
-  createRoot(document.getElementById("app")!).render(<App />);
-};
-bootstrap();
-```
-
-Add `fig-editor` when using `fig-select` / fill picker. Add `fig-lab` when using `propskit-*`.
-
-On `fig-*` and `<dialog is="fig-...">`, use `class` not `className`.
+4. Compose from `fig-*` unless the row needs lab wrappers.
+5. Panel width ~240px. Keep density tight.
 
 ## Field composition
 
-```html
+```tsx
 <fig-field direction="horizontal">
   <label>Opacity</label>
-  <fig-slider value="75" min="0" max="100" text="true" units="%" full></fig-slider>
+  <fig-slider
+    value={String(opacity)}
+    min="0"
+    max="100"
+    text="true"
+    units="%"
+    full
+    onInput={onInput}
+    onChange={onChange}
+  />
 </fig-field>
 ```
 
 - Put control attrs on the control, not a wrapper.
 - Use `full` when the control should stretch.
 - Do not mix unrelated controls in one row unless grouped on purpose.
+- Add `fig-editor` when using `fig-select` / fill picker. Add `fig-lab` when using `propskit-*`.
 
 ## Control heuristics
 
-| Intent | `/propskit` (core) | Lab wrapper |
+| Intent | Core | Lab wrapper |
 |---|---|---|
 | Boolean | `fig-switch` | `propskit-switch` |
 | Continuous number | `fig-slider` | `propskit-slider` |
@@ -100,7 +92,5 @@ Use a horizontal fig-field, with a fig-slider, min=0 max=100 text=true units=%.
 1. Identify intent (boolean, discrete, continuous, color/fill, media, motion).
 2. Pick core vs lab wrapper.
 3. Compose the row; set defaults explicitly.
-4. Check `/propskit` or `/propskit/lab` for an existing example before inventing markup.
-5. Verify `input`/`change` and keyboard.
-
-Primary files: `playground/src/data/sections.ts`, `playground/src/data/labSections.ts`, `fig.js`, `fig-lab.js`.
+4. Wire `onInput` (live) and `onChange` (commit).
+5. Verify keyboard.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rogieking/figui3",
-  "version": "8.9.44",
+  "version": "8.9.45",
   "description": "A lightweight web components library for building Figma plugin and widget UIs with native look and feel",
   "author": "Rogie King",
   "license": "SEE LICENSE IN LICENSE",