@rogieking/figui3 9.4.5 → 9.4.7

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

@@ -83,6 +83,7 @@ useEffect(() => {
 ```
 
 - `display: contents`. Reorders **direct children**. `axis` `vertical` | `horizontal`. `items` selector limits which children reorder (e.g. `items=".row"` to skip headers); `refresh()` re-syncs. Omit `handle` to drag whole rows; set it when rows contain sliders/handles.
+- With fewer than two matching items, children keep `role="listitem"` but drag cursors, handles, focus, and move labels stay inactive until another item is added.
 - Event `reorder`: `{ oldIndex, newIndex, item }` (indices among matching items). Nested drag is ignored for sliders, handles, and canvas controls.
 
 ## AI composer

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

@@ -59,6 +59,8 @@ Observed: `axis`, `handle`, `items`, `disabled`.
 
 `items`: CSS selector for which direct children are reorderable (default: all). Non-matching children stay in place and get `role="none"` unless they have a role. Class/attribute changes on children re-sync automatically; call `refresh()` to force it.
 
+With fewer than two matching items, matching children retain `role="listitem"` but remain non-draggable and receive no generated focus or move label.
+
 Event `reorder`: `{ oldIndex, newIndex, item }`. Indices count matching items, not DOM positions.
 
 Nested drag is ignored for sliders, handles, and canvas controls so inner gestures still work. If a row is still stolen, set `handle` to a drag-affordance selector.

package/.cursor/skills/figui3/components.md

@@ -380,12 +380,18 @@ Handlers below assume `onInput` / `onChange` / `onClick` from [react.md](react.m
   aria-label="Design tools"
   onChange={onChange}
 >
+  <fig-toolbelt-item slot="prepend" value="select">
+    Select
+  </fig-toolbelt-item>
   <fig-toolbelt-group aria-label="Transform tools">
     <fig-toolbelt-item value="move" selected={tool === "move" || undefined}>
       Move
     </fig-toolbelt-item>
     <fig-toolbelt-item value="frame">Frame</fig-toolbelt-item>
   </fig-toolbelt-group>
+  <fig-toolbelt-item slot="append" value="settings">
+    Settings
+  </fig-toolbelt-item>
 </fig-toolbelt>
 ```
 
@@ -394,6 +400,7 @@ Handlers below assume `onInput` / `onChange` / `onClick` from [react.md](react.m
 - Item attrs: `value`, `selected`, `disabled`
 - ArrowLeft/ArrowRight move focus horizontally; ArrowUp/ArrowDown move focus vertically; Enter/Space selects
 - Items stay in light DOM; the internal `part="viewport"` owns scrolling and overflow fades
+- `slot="prepend"` and `slot="append"` keep authored content fixed outside the viewport; slotted items remain selectable and keyboard-navigable
 - Overflow buttons are generated outside the viewport for `overflow="buttons"`
 - Events: `input` / `change` → `currentTarget.value`
 

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

@@ -79,6 +79,7 @@ Public API: `README.md`. React recipes: [components.md](components.md).
 - Events: bubbling `input` and `change` with the selected value
 - `overflow="scrollbar"` is the default and uses buttonless scrolling with the scrollbar hidden; `overflow="buttons"` adds direction-aware paging controls
 - Internal `part="viewport"` owns scrolling and fades; authored items remain direct light-DOM children
+- `slot="prepend"` and `slot="append"` keep authored items, groups, or custom content fixed outside the viewport; slotted items remain in selection and roving keyboard order
 
 ## `.fig-overflow-fade`
 

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [9.4.7]
+
+### Fixed
+
+- Empty `fig-toolbelt` prepend and append slots no longer reserve inline space.
+- The playground now reflects `scrollbar` as the default toolbelt overflow mode.
+
+## [9.4.6]
+
+### Added
+
+- Added fixed `prepend` and `append` slots to `fig-toolbelt`; slotted items remain selectable and keyboard-navigable outside the scrolling fade viewport.
+
+### Changed
+
+- Toolbelt items now delegate horizontal padding to nested controls and preserve variant-aware selected button colors.
+- Toolbelt paging controls honor padding tokens, and slotted groups receive direction-aware separator borders.
+
+### Fixed
+
+- Single-item `fig-reorder` lists retain list semantics without exposing inactive drag handles, cursors, focus, or move labels.
+
 ## [9.4.5]
 
 ### Fixed

package/README.md

@@ -785,17 +785,20 @@ A selectable horizontal or vertical toolbar that keeps authored items in the lig
 
 Wrap related items in `fig-toolbelt-group`; adjacent groups receive a direction-aware separator. Add `aria-label` to groups when the grouping has a meaningful name. Items support `value`, `selected`, and `disabled`. `input` and `change` bubble from the toolbelt with the selected value. ArrowLeft/ArrowRight navigate horizontal toolbelts; ArrowUp/ArrowDown navigate vertical toolbelts. Home and End move to the edges; Enter or Space selects the focused item.
 
+Place an item, group, or custom element in `slot="prepend"` or `slot="append"` to keep it fixed outside the scrolling and faded viewport. Slotted toolbelt items remain part of selection and keyboard navigation.
+
 Use `--fig-toolbelt-gap`, `--fig-toolbelt-group-gap`, `--fig-toolbelt-group-separator-color`, `--fig-toolbelt-overflow-fade-size`, `--fig-toolbelt-padding-block`, `--fig-toolbelt-padding-inline`, `--fig-toolbelt-item-height`, and `--fig-toolbelt-item-padding` to customize layout. The toolbelt fade defaults to `calc(var(--spacer-6) + var(--spacer-2))`.
 
 ```html
 <fig-toolbelt layout="horizontal" overflow="buttons" value="move" aria-label="Design tools">
+  <fig-toolbelt-item slot="prepend" value="move" selected>Move</fig-toolbelt-item>
   <fig-toolbelt-group aria-label="Transform tools">
-    <fig-toolbelt-item value="move" selected>Move</fig-toolbelt-item>
     <fig-toolbelt-item value="frame">Frame</fig-toolbelt-item>
   </fig-toolbelt-group>
   <fig-toolbelt-group aria-label="Shape tools">
     <fig-toolbelt-item value="shape">Shape</fig-toolbelt-item>
   </fig-toolbelt-group>
+  <fig-toolbelt-item slot="append" value="settings">Settings</fig-toolbelt-item>
 </fig-toolbelt>
 ```
 

package/components.css

@@ -1290,70 +1290,6 @@ fig-tab {
     cursor: default;
   }
 }
-
-
-
-fig-toolbelt-item {
-  display: inline-flex;
-  flex-shrink: 0;
-  align-items: center;
-  justify-content: center;
-  height: var(--fig-toolbelt-item-height, var(--control-height));
-  padding-inline: var(--fig-toolbelt-item-padding, var(--spacer-2));
-  border-radius: var(--radius-medium);
-  color: var(--figma-color-text-secondary);
-  line-height: var(--line-height);
-  cursor: default;
-  user-select: none;
-
-  &:has(> fig-tooltip > fig-button[icon]:not([icon="false"])) {
-    padding-inline: 0;
-  }
-
-  &[selected]:not([selected="false"]) {
-    color: var(--figma-color-text);
-    background-color: var(--figma-color-bg-secondary);
-
-    fig-button{
-      color: var(--figma-color-icon-onbrand);
-      background-color: var(--figma-color-bg-brand);
-    }
-  }
-
-  &:hover {
-    background-color: var(--figma-color-bg-secondary);
-  }
-
-  &:focus-visible,
-  &[data-focus-visible] {
-    outline: var(--figma-focus-outline);
-    outline-offset: var(--figma-focus-outline-offset);
-  }
-
-  &[disabled]:not([disabled="false"]) {
-    opacity: 0.4;
-    pointer-events: none;
-  }
-}
-
-fig-toolbelt-group {
-  display: inline-flex;
-  flex-flow: row nowrap;
-  flex-shrink: 0;
-  align-items: stretch;
-  gap: var(--fig-toolbelt-gap);
-  min-width: 0;
-
-  & + fig-toolbelt-group {
-    margin-inline-start: calc(
-      var(--fig-toolbelt-group-gap) - var(--fig-toolbelt-gap)
-    );
-    padding-inline-start: var(--fig-toolbelt-group-gap);
-    border-inline-start: 1px solid
-      var(--fig-toolbelt-group-separator-color);
-  }
-}
-
 fig-tab-content {
   display: block;
   width: 100%;
@@ -1474,171 +1410,6 @@ fig-tabs,
   }
 }
 
-fig-toolbelt {
-  --fig-toolbelt-gap: var(--spacer-1);
-  --fig-toolbelt-group-gap: var(--spacer-2);
-  --fig-toolbelt-group-separator-color: var(--figma-color-border);
-  --fig-toolbelt-overflow-fade-size: calc(var(--spacer-6) + var(--spacer-2));
-  --fig-toolbelt-padding-block: var(--spacer-2);
-  --fig-toolbelt-padding-inline: var(--spacer-2);
-
-  position: relative;
-  display: inline-block;
-  box-sizing: border-box;
-  width: 100%;
-  min-width: 0;
-  margin: 0;
-  background: var(--figma-color-bg) !important;
-  border-radius: var(--radius-large);
-
-  &::after{
-    content: "";
-    position: absolute;
-    inset: 0;
-    pointer-events: none;
-    z-index: 10;
-    box-shadow: var(--figma-elevation-100-canvas);
-    border-radius: var(--radius-large);
-  }
-
-  &[disabled]:not([disabled="false"]) {
-    pointer-events: none;
-  }
-
-  &::part(frame) {
-    position: relative;
-    display: flex;
-    flex-flow: row nowrap;
-    width: 100%;
-    height: 100%;
-    min-width: 0;
-    min-height: 0;
-  }
-
-  &::part(viewport) {
-    display: flex;
-    flex: 1 1 auto;
-    flex-flow: row nowrap;
-    box-sizing: border-box;
-    gap: var(--fig-toolbelt-gap);
-    width: 100%;
-    min-width: 0;
-    padding: var(--fig-toolbelt-padding-block)
-      var(--fig-toolbelt-padding-inline);
-    overflow: auto hidden;
-    scrollbar-width: none;
-  }
-
-  &::part(viewport)::-webkit-scrollbar {
-    display: none;
-  }
-
-  > .fig-overflow {
-    position: absolute;
-    top: 0;
-    bottom: 0;
-    z-index: 3;
-    width: var(--control-height);
-    height: auto;
-    margin: 0;
-  }
-
-  > .fig-overflow-start {
-    left: 0;
-    right: auto;
-    box-shadow: 1px 0 0 0 var(--figma-color-bordertranslucent);
-
-    &::before {
-      border-radius: var(--radius-medium) 0 0 var(--radius-medium);
-    }
-
-    .fig-overflow-chevron {
-      rotate: 90deg;
-    }
-  }
-
-  > .fig-overflow-end {
-    right: 0;
-    left: auto;
-    box-shadow: -1px 0 0 0 var(--figma-color-bordertranslucent);
-
-    &::before {
-      border-radius: 0 var(--radius-medium) var(--radius-medium) 0;
-    }
-
-    .fig-overflow-chevron {
-      rotate: -90deg;
-    }
-  }
-
-  &[layout="vertical"] {
-    width: fit-content;
-    max-width: 100%;
-
-    &::part(frame),
-    &::part(viewport) {
-      flex-flow: column nowrap;
-    }
-
-    &::part(viewport) {
-      overflow: hidden auto;
-    }
-
-    fig-toolbelt-group {
-      flex-flow: column nowrap;
-      width: 100%;
-
-      & + fig-toolbelt-group {
-        margin-block-start: calc(
-          var(--fig-toolbelt-group-gap) - var(--fig-toolbelt-gap)
-        );
-        margin-inline-start: 0;
-        padding-block-start: var(--fig-toolbelt-group-gap);
-        padding-inline-start: 0;
-        border-block-start: 1px solid
-          var(--fig-toolbelt-group-separator-color);
-        border-inline-start: 0;
-      }
-    }
-
-    > .fig-overflow {
-      top: auto;
-      right: 0;
-      left: 0;
-      width: auto;
-      height: var(--control-height);
-    }
-
-    > .fig-overflow-start {
-      top: 0;
-      bottom: auto;
-      box-shadow: 0 1px 0 0 var(--figma-color-bordertranslucent);
-
-      &::before {
-        border-radius: var(--radius-medium) var(--radius-medium) 0 0;
-      }
-
-      .fig-overflow-chevron {
-        rotate: 180deg;
-      }
-    }
-
-    > .fig-overflow-end {
-      top: auto;
-      bottom: 0;
-      box-shadow: 0 -1px 0 0 var(--figma-color-bordertranslucent);
-
-      &::before {
-        border-radius: 0 0 var(--radius-medium) var(--radius-medium);
-      }
-
-      .fig-overflow-chevron {
-        rotate: 0deg;
-      }
-    }
-  }
-}
-
 /* Avatar */
 fig-avatar,
 .fig-avatar {
@@ -5609,13 +5380,6 @@ fig-skeleton {
   overflow-y: auto;
 }
 
-fig-toolbelt::part(viewport) {
-  --fig-overflow-fade-size: var(--fig-toolbelt-overflow-fade-size);
-  --fig-overflow-fade-clear-top: 0px;
-
-  overflow-y: auto;
-}
-
 .fig-overflow-fade.fig-overflow-fade-horizontal {
   --fig-overflow-fade-clear-left: 0px;
 
@@ -5623,11 +5387,325 @@ fig-toolbelt::part(viewport) {
   overflow-y: hidden;
 }
 
-fig-toolbelt:not([layout="vertical"])::part(viewport) {
-  --fig-overflow-fade-clear-left: 0px;
+/* Toolbelt */
+fig-toolbelt-item {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  height: var(--fig-toolbelt-item-height, var(--control-height));
+  padding-inline: 0;
+  border-radius: var(--radius-medium);
+  color: var(--figma-color-text-secondary);
+  line-height: var(--line-height);
+  cursor: default;
+  user-select: none;
 
-  overflow-x: auto;
-  overflow-y: hidden;
+  &:has(> fig-tooltip > fig-button[icon]:not([icon="false"])) {
+    padding-inline: 0;
+  }
+
+  &[selected]:not([selected="false"]) {
+    color: var(--figma-color-text);
+    background-color: var(--figma-color-bg-secondary);
+
+    fig-button,
+    fig-button:hover {
+      color: var(--figma-color-icon-onbrand);
+      background-color: var(--figma-color-bg-brand);
+    }
+    fig-button[variant="secondary"],
+    fig-button[variant="ghost"],
+    fig-button[variant="secondary"]:hover,
+    fig-button[variant="ghost"]:hover {
+      color: var(--figma-color-icon-selected);
+      background-color: var(--figma-color-bg-selected);
+    }
+  }
+
+  &:hover {
+    background-color: var(--figma-color-bg-secondary);
+  }
+
+  &:focus-visible,
+  &[data-focus-visible] {
+    outline: var(--figma-focus-outline);
+    outline-offset: var(--figma-focus-outline-offset);
+  }
+
+  &[disabled]:not([disabled="false"]) {
+    opacity: 0.4;
+    pointer-events: none;
+  }
+}
+
+fig-toolbelt-group {
+  display: inline-flex;
+  flex-flow: row nowrap;
+  flex-shrink: 0;
+  align-items: stretch;
+  gap: var(--fig-toolbelt-gap);
+  min-width: 0;
+
+  &:is(:not([slot]), [slot=""])
+    + fig-toolbelt-group:is(:not([slot]), [slot=""]),
+  &[slot="prepend"] + fig-toolbelt-group[slot="prepend"],
+  &[slot="append"] + fig-toolbelt-group[slot="append"] {
+    margin-inline-start: calc(
+      var(--fig-toolbelt-group-gap) - var(--fig-toolbelt-gap)
+    );
+    padding-inline-start: var(--fig-toolbelt-group-gap);
+    border-inline-start: 1px solid
+      var(--fig-toolbelt-group-separator-color);
+  }
+
+  &[slot="prepend"] {
+    padding-inline-end: var(--fig-toolbelt-group-gap);
+    border-inline-end: 1px solid
+      var(--fig-toolbelt-group-separator-color);
+  }
+
+  &[slot="append"] {
+    padding-inline-start: var(--fig-toolbelt-group-gap);
+    border-inline-start: 1px solid
+      var(--fig-toolbelt-group-separator-color);
+  }
+}
+
+fig-toolbelt {
+  --fig-toolbelt-gap: var(--spacer-1);
+  --fig-toolbelt-group-gap: var(--spacer-2);
+  --fig-toolbelt-group-separator-color: var(--figma-color-border);
+  --fig-toolbelt-overflow-fade-size: calc(var(--spacer-6) + var(--spacer-2));
+  --fig-toolbelt-padding-block: var(--spacer-2);
+  --fig-toolbelt-padding-inline: var(--spacer-2);
+
+  position: relative;
+  display: inline-block;
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  margin: 0;
+  background: var(--figma-color-bg) !important;
+  border-radius: var(--radius-large);
+
+  &::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 10;
+    box-shadow: var(--figma-elevation-100-canvas);
+    border-radius: var(--radius-large);
+  }
+
+  &[disabled]:not([disabled="false"]) {
+    pointer-events: none;
+  }
+
+  &::part(frame),
+  &::part(scroll-region) {
+    position: relative;
+    display: flex;
+    flex-flow: row nowrap;
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    min-height: 0;
+  }
+
+  &::part(scroll-region) {
+    flex: 1 1 auto;
+  }
+
+  &::part(prepend),
+  &::part(append) {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: stretch;
+    gap: var(--fig-toolbelt-gap);
+    padding-block: var(--fig-toolbelt-padding-block);
+  }
+
+  &::part(prepend) {
+    padding-inline-start: var(--fig-toolbelt-padding-inline);
+  }
+
+  &::part(append) {
+    padding-inline-end: var(--fig-toolbelt-padding-inline);
+  }
+
+  &::part(viewport) {
+    --fig-overflow-fade-size: var(--fig-toolbelt-overflow-fade-size);
+    --fig-overflow-fade-clear-top: 0px;
+
+    display: flex;
+    flex: 1 1 auto;
+    flex-flow: row nowrap;
+    box-sizing: border-box;
+    gap: var(--fig-toolbelt-gap);
+    width: 100%;
+    min-width: 0;
+    padding: var(--fig-toolbelt-padding-block)
+      var(--fig-toolbelt-padding-inline);
+    overflow: auto;
+    scrollbar-width: none;
+  }
+
+  &::part(viewport)::-webkit-scrollbar {
+    display: none;
+  }
+
+  &:not([layout="vertical"])::part(viewport) {
+    --fig-overflow-fade-clear-left: 0px;
+
+    overflow-x: auto;
+    overflow-y: hidden;
+  }
+
+  > .fig-overflow {
+    position: absolute;
+    top: var(--fig-toolbelt-padding-block);
+    bottom: var(--fig-toolbelt-padding-block);
+    z-index: 3;
+    width: var(--control-height);
+    height: auto;
+    margin: 0;
+  }
+
+  > .fig-overflow-start {
+    left: 0;
+    right: auto;
+    box-shadow: 1px 0 0 0 var(--figma-color-bordertranslucent);
+
+    &::before {
+      border-radius: var(--radius-medium) 0 0 var(--radius-medium);
+    }
+
+    .fig-overflow-chevron {
+      rotate: 90deg;
+    }
+  }
+
+  > .fig-overflow-end {
+    right: 0;
+    left: auto;
+    box-shadow: -1px 0 0 0 var(--figma-color-bordertranslucent);
+
+    &::before {
+      border-radius: 0 var(--radius-medium) var(--radius-medium) 0;
+    }
+
+    .fig-overflow-chevron {
+      rotate: -90deg;
+    }
+  }
+
+  &[layout="vertical"] {
+    width: fit-content;
+    max-width: 100%;
+
+    &::part(frame),
+    &::part(scroll-region),
+    &::part(viewport) {
+      flex-flow: column nowrap;
+    }
+
+    &::part(prepend),
+    &::part(append) {
+      flex-flow: column nowrap;
+      padding-block: 0;
+      padding-inline: var(--fig-toolbelt-padding-inline);
+    }
+
+    &::part(prepend) {
+      padding-block-start: var(--fig-toolbelt-padding-block);
+    }
+
+    &::part(append) {
+      padding-block-end: var(--fig-toolbelt-padding-block);
+    }
+
+    &::part(viewport) {
+      overflow: hidden auto;
+    }
+
+    fig-toolbelt-group {
+      flex-flow: column nowrap;
+      width: 100%;
+
+      &:is(:not([slot]), [slot=""])
+        + fig-toolbelt-group:is(:not([slot]), [slot=""]),
+      &[slot="prepend"] + fig-toolbelt-group[slot="prepend"],
+      &[slot="append"] + fig-toolbelt-group[slot="append"] {
+        margin-block-start: calc(
+          var(--fig-toolbelt-group-gap) - var(--fig-toolbelt-gap)
+        );
+        margin-inline-start: 0;
+        padding-block-start: var(--fig-toolbelt-group-gap);
+        padding-inline-start: 0;
+        border-block-start: 1px solid
+          var(--fig-toolbelt-group-separator-color);
+        border-inline-start: 0;
+      }
+
+      &[slot="prepend"] {
+        padding-block-end: calc(
+          var(--fig-toolbelt-group-gap) - var(--fig-toolbelt-gap)
+        );
+        padding-inline-end: 0;
+        border-block-end: 1px solid
+          var(--fig-toolbelt-group-separator-color);
+        border-inline-end: 0;
+      }
+
+      &[slot="append"] {
+        padding-block-start: calc(
+          var(--fig-toolbelt-group-gap) - var(--fig-toolbelt-gap)
+        );
+        padding-inline-start: 0;
+        border-block-start: 1px solid
+          var(--fig-toolbelt-group-separator-color);
+        border-inline-start: 0;
+      }
+    }
+
+    > .fig-overflow {
+      top: auto;
+      right: var(--fig-toolbelt-padding-inline);
+      left: var(--fig-toolbelt-padding-inline);
+      width: auto;
+      height: var(--control-height);
+    }
+
+    > .fig-overflow-start {
+      top: 0;
+      bottom: auto;
+      box-shadow: 0 1px 0 0 var(--figma-color-bordertranslucent);
+
+      &::before {
+        border-radius: var(--radius-medium) var(--radius-medium) 0 0;
+      }
+
+      .fig-overflow-chevron {
+        rotate: 180deg;
+      }
+    }
+
+    > .fig-overflow-end {
+      top: auto;
+      bottom: 0;
+      box-shadow: 0 -1px 0 0 var(--figma-color-bordertranslucent);
+
+      &::before {
+        border-radius: 0 0 var(--radius-medium) var(--radius-medium);
+      }
+
+      .fig-overflow-chevron {
+        rotate: 0deg;
+      }
+    }
+  }
 }
 
 @supports (animation-timeline: scroll(self block)) {