@fragments-sdk/ui 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Customizable UI components built on Base UI headless primitives",
   "type": "module",
   "main": "src/index.ts",
@@ -36,7 +36,7 @@
     "react-dom": "^19.0.0",
     "sass": "^1.83.0",
     "typescript": "^5.7.0",
-    "@fragments-sdk/cli": "0.4.1"
+    "@fragments-sdk/cli": "0.4.4"
   },
   "files": [
     "src",

package/src/components/Combobox/Combobox.fragment.tsx

@@ -95,6 +95,11 @@ export default defineSegment({
       description: 'Auto-highlight first matching item while filtering',
       default: 'true',
     },
+    maxVisibleItems: {
+      type: 'number',
+      description: 'Maximum visible options before scrolling. Shows half of the next item as a scroll hint.',
+      default: '4',
+    },
   },
 
   relations: [
@@ -111,6 +116,7 @@ export default defineSegment({
       'placeholder: string - input placeholder text',
       'disabled: boolean - disable combobox',
       'autoHighlight: boolean - auto-highlight first match',
+      'maxVisibleItems: number - max visible options before scrolling (default 4)',
     ],
     scenarioTags: [
       'form.combobox',
@@ -204,6 +210,50 @@ export default defineSegment({
         </StatefulCombobox>
       ),
     },
+    {
+      name: 'Scrollable List',
+      description: 'Long list with scroll hint — shows 4 items with half-peek of the 5th',
+      render: () => (
+        <StatefulCombobox placeholder="Search languages...">
+          <Combobox.Input />
+          <Combobox.Content>
+            <Combobox.Empty>No results found</Combobox.Empty>
+            <Combobox.Item value="js">JavaScript</Combobox.Item>
+            <Combobox.Item value="ts">TypeScript</Combobox.Item>
+            <Combobox.Item value="py">Python</Combobox.Item>
+            <Combobox.Item value="rs">Rust</Combobox.Item>
+            <Combobox.Item value="go">Go</Combobox.Item>
+            <Combobox.Item value="rb">Ruby</Combobox.Item>
+            <Combobox.Item value="java">Java</Combobox.Item>
+            <Combobox.Item value="swift">Swift</Combobox.Item>
+            <Combobox.Item value="kt">Kotlin</Combobox.Item>
+            <Combobox.Item value="cpp">C++</Combobox.Item>
+          </Combobox.Content>
+        </StatefulCombobox>
+      ),
+    },
+    {
+      name: 'Custom Max Visible Items',
+      description: 'Show 6 items before scrolling with half-peek scroll hint',
+      render: () => (
+        <StatefulCombobox placeholder="Search cities...">
+          <Combobox.Input />
+          <Combobox.Content maxVisibleItems={6}>
+            <Combobox.Empty>No results found</Combobox.Empty>
+            <Combobox.Item value="nyc">New York</Combobox.Item>
+            <Combobox.Item value="lon">London</Combobox.Item>
+            <Combobox.Item value="tok">Tokyo</Combobox.Item>
+            <Combobox.Item value="par">Paris</Combobox.Item>
+            <Combobox.Item value="syd">Sydney</Combobox.Item>
+            <Combobox.Item value="ber">Berlin</Combobox.Item>
+            <Combobox.Item value="tor">Toronto</Combobox.Item>
+            <Combobox.Item value="sin">Singapore</Combobox.Item>
+            <Combobox.Item value="dub">Dubai</Combobox.Item>
+            <Combobox.Item value="sao">São Paulo</Combobox.Item>
+          </Combobox.Content>
+        </StatefulCombobox>
+      ),
+    },
     {
       name: 'Disabled',
       description: 'Disabled combobox',

package/src/components/Combobox/Combobox.module.scss

@@ -152,9 +152,9 @@
   }
 }
 
-// Positioner
+// Positioner — z-index must exceed Dialog positioner (51)
 .positioner {
-  z-index: 50;
+  z-index: 52;
   outline: none;
 }
 
@@ -162,9 +162,20 @@
 .popup {
   @include surface-elevated;
 
+  // Item height derived from text-base font + vertical padding
+  --_item-h: calc(
+    var(--fui-font-size-sm, #{$fui-font-size-sm}) * var(--fui-line-height-normal, #{$fui-line-height-normal}) +
+    var(--fui-space-2, #{$fui-space-2}) * 2
+  );
+
   min-width: var(--anchor-width);
-  max-height: 20rem;
-  overflow-y: auto;
+  // Show N items + half-peek scroll hint (default 4.5 items)
+  // !important needed to override Base UI's inline max-height: 100%
+  max-height: calc(
+    var(--_item-h) * var(--fui-select-max-items, 4.5) +
+    var(--fui-space-1, #{$fui-space-1}) * 2
+  ) !important;
+  overflow-y: auto !important;
   padding: var(--fui-space-1, $fui-space-1);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 

package/src/components/Combobox/index.tsx

@@ -42,6 +42,8 @@ export interface ComboboxContentProps extends React.HTMLAttributes<HTMLDivElemen
   children: React.ReactNode;
   sideOffset?: number;
   align?: 'start' | 'center' | 'end';
+  /** Maximum number of visible options before scrolling. Shows half of the next item as a scroll hint. @default 4 */
+  maxVisibleItems?: number;
 }
 
 export interface ComboboxItemProps {
@@ -310,10 +312,15 @@ function ComboboxContent({
   className,
   sideOffset = 4,
   align = 'start',
+  maxVisibleItems,
   ...htmlProps
 }: ComboboxContentProps) {
   const popupClasses = [styles.popup, className].filter(Boolean).join(' ');
 
+  const popupStyle = maxVisibleItems != null
+    ? { '--fui-select-max-items': maxVisibleItems + 0.5, ...htmlProps.style } as React.CSSProperties
+    : htmlProps.style;
+
   return (
     <BaseCombobox.Portal>
       <BaseCombobox.Positioner
@@ -322,7 +329,7 @@ function ComboboxContent({
         align={align}
         className={styles.positioner}
       >
-        <BaseCombobox.Popup {...htmlProps} className={popupClasses}>
+        <BaseCombobox.Popup {...htmlProps} className={popupClasses} style={popupStyle}>
           {children}
         </BaseCombobox.Popup>
       </BaseCombobox.Positioner>

package/src/components/Menu/Menu.module.scss

@@ -1,9 +1,9 @@
 @use '../../tokens/variables' as *;
 @use '../../tokens/mixins' as *;
 
-// Positioner
+// Positioner — z-index must exceed Dialog positioner (51)
 .positioner {
-  z-index: 50;
+  z-index: 52;
   outline: none;
 }
 

package/src/components/Popover/Popover.module.scss

@@ -1,9 +1,9 @@
 @use '../../tokens/variables' as *;
 @use '../../tokens/mixins' as *;
 
-// Positioner
+// Positioner — z-index must exceed Dialog positioner (51)
 .positioner {
-  z-index: 50;
+  z-index: 52;
   outline: none;
 }
 

package/src/components/Select/Select.fragment.tsx

@@ -81,6 +81,11 @@ export default defineSegment({
       description: 'Disable the select',
       default: 'false',
     },
+    maxVisibleItems: {
+      type: 'number',
+      description: 'Maximum visible options before scrolling. Shows half of the next item as a scroll hint.',
+      default: '4',
+    },
   },
 
   relations: [
@@ -95,6 +100,7 @@ export default defineSegment({
       'onValueChange: (value) => void - selection handler',
       'placeholder: string - placeholder text',
       'disabled: boolean - disable select',
+      'maxVisibleItems: number - max visible options before scrolling (default 4)',
     ],
     scenarioTags: [
       'form.select',
@@ -166,6 +172,48 @@ export default defineSegment({
         </StatefulSelect>
       ),
     },
+    {
+      name: 'Scrollable List',
+      description: 'Long list with scroll hint — shows 4 items with half-peek of the 5th to indicate more',
+      render: () => (
+        <StatefulSelect placeholder="Select a timezone">
+          <Select.Trigger />
+          <Select.Content>
+            <Select.Item value="utc-8">Pacific Time (UTC-8)</Select.Item>
+            <Select.Item value="utc-7">Mountain Time (UTC-7)</Select.Item>
+            <Select.Item value="utc-6">Central Time (UTC-6)</Select.Item>
+            <Select.Item value="utc-5">Eastern Time (UTC-5)</Select.Item>
+            <Select.Item value="utc-4">Atlantic Time (UTC-4)</Select.Item>
+            <Select.Item value="utc+0">GMT (UTC+0)</Select.Item>
+            <Select.Item value="utc+1">Central European (UTC+1)</Select.Item>
+            <Select.Item value="utc+5.5">India Standard (UTC+5:30)</Select.Item>
+            <Select.Item value="utc+8">China Standard (UTC+8)</Select.Item>
+            <Select.Item value="utc+9">Japan Standard (UTC+9)</Select.Item>
+          </Select.Content>
+        </StatefulSelect>
+      ),
+    },
+    {
+      name: 'Custom Max Visible Items',
+      description: 'Show 6 items before scrolling with half-peek scroll hint',
+      render: () => (
+        <StatefulSelect placeholder="Select a color">
+          <Select.Trigger />
+          <Select.Content maxVisibleItems={6}>
+            <Select.Item value="red">Red</Select.Item>
+            <Select.Item value="orange">Orange</Select.Item>
+            <Select.Item value="yellow">Yellow</Select.Item>
+            <Select.Item value="green">Green</Select.Item>
+            <Select.Item value="blue">Blue</Select.Item>
+            <Select.Item value="indigo">Indigo</Select.Item>
+            <Select.Item value="violet">Violet</Select.Item>
+            <Select.Item value="pink">Pink</Select.Item>
+            <Select.Item value="teal">Teal</Select.Item>
+            <Select.Item value="cyan">Cyan</Select.Item>
+          </Select.Content>
+        </StatefulSelect>
+      ),
+    },
     {
       name: 'Disabled',
       description: 'Disabled select',

package/src/components/Select/Select.module.scss

@@ -72,9 +72,9 @@
   }
 }
 
-// Positioner
+// Positioner — z-index must exceed Dialog positioner (51)
 .positioner {
-  z-index: 50;
+  z-index: 52;
   outline: none;
 }
 
@@ -82,9 +82,20 @@
 .popup {
   @include surface-elevated;
 
+  // Item height derived from text-base font + vertical padding
+  --_item-h: calc(
+    var(--fui-font-size-sm, #{$fui-font-size-sm}) * var(--fui-line-height-normal, #{$fui-line-height-normal}) +
+    var(--fui-space-2, #{$fui-space-2}) * 2
+  );
+
   min-width: var(--anchor-width);
-  max-height: 20rem;
-  overflow-y: auto;
+  // Show N items + half-peek scroll hint (default 4.5 items)
+  // !important needed to override Base UI's inline max-height: 100%
+  max-height: calc(
+    var(--_item-h) * var(--fui-select-max-items, 4.5) +
+    var(--fui-space-1, #{$fui-space-1}) * 2
+  ) !important;
+  overflow-y: auto !important;
   padding: var(--fui-space-1, $fui-space-1);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 

package/src/components/Select/index.tsx

@@ -39,6 +39,8 @@ export interface SelectContentProps extends React.HTMLAttributes<HTMLDivElement>
   children: React.ReactNode;
   sideOffset?: number;
   align?: 'start' | 'center' | 'end';
+  /** Maximum number of visible options before scrolling. Shows half of the next item as a scroll hint. @default 4 */
+  maxVisibleItems?: number;
 }
 
 export interface SelectItemProps {
@@ -236,10 +238,15 @@ function SelectContent({
   className,
   sideOffset = 4,
   align = 'start',
+  maxVisibleItems,
   ...htmlProps
 }: SelectContentProps) {
   const popupClasses = [styles.popup, className].filter(Boolean).join(' ');
 
+  const popupStyle = maxVisibleItems != null
+    ? { '--fui-select-max-items': maxVisibleItems + 0.5, ...htmlProps.style } as React.CSSProperties
+    : htmlProps.style;
+
   return (
     <BaseSelect.Portal>
       <BaseSelect.Positioner
@@ -247,7 +254,7 @@ function SelectContent({
         align={align}
         className={styles.positioner}
       >
-        <BaseSelect.Popup {...htmlProps} className={popupClasses}>
+        <BaseSelect.Popup {...htmlProps} className={popupClasses} style={popupStyle}>
           {children}
         </BaseSelect.Popup>
       </BaseSelect.Positioner>
@@ -256,18 +263,18 @@ function SelectContent({
 }
 
 function SelectItem({ children, value, disabled, className }: SelectItemProps) {
-  const context = React.useContext(SelectContext);
+  const { itemsRef, incrementItemsVersion } = React.useContext(SelectContext);
   const classes = [styles.item, className].filter(Boolean).join(' ');
 
   // Register this item's children in the registry so the trigger can display them
   React.useEffect(() => {
-    context.itemsRef.current.set(value, children);
+    itemsRef.current.set(value, children);
     // Trigger re-render of trigger to show the registered content
-    context.incrementItemsVersion();
+    incrementItemsVersion();
     return () => {
-      context.itemsRef.current.delete(value);
+      itemsRef.current.delete(value);
     };
-  }, [context, value, children]);
+  }, [itemsRef, incrementItemsVersion, value, children]);
 
   return (
     <BaseSelect.Item value={value} disabled={disabled} className={classes}>

package/src/components/Text/Text.module.scss

@@ -2,6 +2,7 @@
 
 .text {
   font-family: var(--fui-font-sans, $fui-font-sans);
+  color: var(--fui-text-primary, $fui-text-primary);
   margin: 0;
 }