@fragments-sdk/ui 0.1.0

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

@@ -0,0 +1,173 @@
+import React, { useState } from 'react';
+import { defineSegment } from '@fragments/core';
+import { Select } from './index.js';
+
+// Stateful wrapper for interactive demos
+function StatefulSelect(props: React.ComponentProps<typeof Select> & {
+  children: React.ReactNode;
+  initialValue?: string;
+}) {
+  const { initialValue, children, ...rest } = props;
+  const [value, setValue] = useState<string | null>(initialValue ?? null);
+  return (
+    <Select {...rest} value={value} onValueChange={setValue}>
+      {children}
+    </Select>
+  );
+}
+
+export default defineSegment({
+  component: Select,
+
+  meta: {
+    name: 'Select',
+    description: 'Dropdown for choosing from a list of options. Use when there are more than 4-5 choices that would clutter the UI.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['select', 'dropdown', 'form', 'options', 'picker'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Choosing from a predefined list of options',
+      'More than 4-5 options that would clutter UI as radio buttons',
+      'Space-constrained forms',
+      'When users need to see all options at once',
+    ],
+    whenNot: [
+      'Very few options (2-3) - use radio buttons',
+      'Users might type custom values - use Combobox',
+      'Multiple selections needed - use Checkbox group or MultiSelect',
+      'Actions, not selection - use Menu',
+    ],
+    guidelines: [
+      'Include a placeholder that explains what to select',
+      'Group related options with SelectGroup',
+      'Keep option text concise',
+      'Order options logically (alphabetical, by frequency, or by category)',
+    ],
+    accessibility: [
+      'Full keyboard navigation support',
+      'Type-ahead search within options',
+      'Proper ARIA roles and attributes',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Select trigger and content',
+      required: true,
+    },
+    value: {
+      type: 'string',
+      description: 'Controlled selected value',
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Default selected value (uncontrolled)',
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Called when selection changes',
+    },
+    placeholder: {
+      type: 'string',
+      description: 'Placeholder text when no value selected',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable the select',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Menu', relationship: 'alternative', note: 'Use Menu for action-based dropdowns' },
+    { component: 'Input', relationship: 'sibling', note: 'Use Input for free-form text entry' },
+    { component: 'Checkbox', relationship: 'alternative', note: 'Use Checkbox group for multiple selections' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - controlled selected value',
+      'onValueChange: (value) => void - selection handler',
+      'placeholder: string - placeholder text',
+      'disabled: boolean - disable select',
+    ],
+    scenarioTags: [
+      'form.select',
+      'form.dropdown',
+      'input.options',
+    ],
+    a11yRules: ['A11Y_SELECT_KEYBOARD', 'A11Y_SELECT_LABEL'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic select dropdown',
+      render: () => (
+        <StatefulSelect placeholder="Select a fruit">
+          <Select.Trigger />
+          <Select.Content>
+            <Select.Item value="apple">Apple</Select.Item>
+            <Select.Item value="banana">Banana</Select.Item>
+            <Select.Item value="orange">Orange</Select.Item>
+            <Select.Item value="grape">Grape</Select.Item>
+          </Select.Content>
+        </StatefulSelect>
+      ),
+    },
+    {
+      name: 'With Groups',
+      description: 'Options organized into groups',
+      render: () => (
+        <StatefulSelect placeholder="Select a country">
+          <Select.Trigger />
+          <Select.Content>
+            <Select.Group>
+              <Select.GroupLabel>North America</Select.GroupLabel>
+              <Select.Item value="us">United States</Select.Item>
+              <Select.Item value="ca">Canada</Select.Item>
+              <Select.Item value="mx">Mexico</Select.Item>
+            </Select.Group>
+            <Select.Group>
+              <Select.GroupLabel>Europe</Select.GroupLabel>
+              <Select.Item value="uk">United Kingdom</Select.Item>
+              <Select.Item value="de">Germany</Select.Item>
+              <Select.Item value="fr">France</Select.Item>
+            </Select.Group>
+          </Select.Content>
+        </StatefulSelect>
+      ),
+    },
+    {
+      name: 'With Disabled Options',
+      description: 'Some options are disabled',
+      render: () => (
+        <StatefulSelect placeholder="Select a plan">
+          <Select.Trigger />
+          <Select.Content>
+            <Select.Item value="free">Free</Select.Item>
+            <Select.Item value="pro">Pro</Select.Item>
+            <Select.Item value="enterprise" disabled>Enterprise (Contact Sales)</Select.Item>
+          </Select.Content>
+        </StatefulSelect>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Disabled select',
+      render: () => (
+        <Select disabled placeholder="Select an option">
+          <Select.Trigger />
+          <Select.Content>
+            <Select.Item value="1">Option 1</Select.Item>
+          </Select.Content>
+        </Select>
+      ),
+    },
+  ],
+});

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

@@ -0,0 +1,187 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Trigger button
+.trigger {
+  @include button-reset;
+  @include interactive-base;
+  @include text-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-2, $fui-space-2);
+  width: 100%;
+  min-width: 10rem;
+  height: var(--fui-input-height, $fui-input-height);
+  padding: 0 var(--fui-space-3, $fui-space-3);
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  text-align: left;
+
+  &:hover:not([data-disabled]) {
+    border-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &[data-popup-open] {
+    border-color: var(--fui-color-accent, $fui-color-accent);
+  }
+
+  &[data-disabled] {
+    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+// Value display
+.value {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+
+  &[data-placeholder] {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+// Chevron icon
+.icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  transition: transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-popup-open] > & {
+    transform: rotate(180deg);
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// Positioner
+.positioner {
+  z-index: 50;
+  outline: none;
+}
+
+// Popup container
+.popup {
+  @include surface-elevated;
+
+  min-width: var(--anchor-width);
+  max-height: 20rem;
+  overflow-y: auto;
+  padding: var(--fui-space-1, $fui-space-1);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+
+  // Animation
+  opacity: 0;
+  transform: scale(0.95);
+  transform-origin: var(--transform-origin);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &[data-open] {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+// Individual option
+.item {
+  @include button-reset;
+  @include text-base;
+
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  width: 100%;
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  cursor: pointer;
+  outline: none;
+
+  &[data-highlighted] {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &[data-selected] {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+    color: var(--fui-text-inverse, $fui-text-inverse);
+
+    &[data-highlighted] {
+      background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    }
+  }
+
+  &[data-disabled] {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+    cursor: not-allowed;
+  }
+}
+
+// Selection indicator (checkmark)
+.itemIndicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+  margin-left: auto;
+
+  svg {
+    width: 0.875rem;
+    height: 0.875rem;
+  }
+}
+
+// Group container
+.group {
+  &:not(:first-child) {
+    margin-top: var(--fui-space-1, $fui-space-1);
+    padding-top: var(--fui-space-1, $fui-space-1);
+    border-top: 1px solid var(--fui-border, $fui-border);
+  }
+}
+
+// Group label
+.groupLabel {
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+// Arrow
+.arrow {
+  width: 10px;
+  height: 10px;
+  transform: rotate(45deg);
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border, $fui-border);
+
+  &[data-side='top'] {
+    border-top: none;
+    border-left: none;
+  }
+
+  &[data-side='bottom'] {
+    border-bottom: none;
+    border-right: none;
+  }
+}

package/src/components/Select/index.tsx

@@ -0,0 +1,233 @@
+import * as React from 'react';
+import { Select as BaseSelect } from '@base-ui/react/select';
+import styles from './Select.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type SelectValue = string;
+
+export interface SelectOption {
+  value: SelectValue;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface SelectProps {
+  children: React.ReactNode;
+  value?: SelectValue | null;
+  defaultValue?: SelectValue;
+  onValueChange?: (value: SelectValue | null) => void;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  required?: boolean;
+  name?: string;
+  placeholder?: string;
+}
+
+export interface SelectTriggerProps {
+  children?: React.ReactNode;
+  placeholder?: string;
+  className?: string;
+}
+
+export interface SelectContentProps {
+  children: React.ReactNode;
+  className?: string;
+  sideOffset?: number;
+  align?: 'start' | 'center' | 'end';
+}
+
+export interface SelectItemProps {
+  children: React.ReactNode;
+  value: SelectValue;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface SelectGroupProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface SelectGroupLabelProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function ChevronDownIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+// ============================================
+// Context for placeholder
+// ============================================
+
+const SelectContext = React.createContext<{ placeholder?: string }>({});
+
+// ============================================
+// Components
+// ============================================
+
+function SelectRoot({
+  children,
+  value,
+  defaultValue,
+  onValueChange,
+  open,
+  defaultOpen,
+  onOpenChange,
+  disabled,
+  required,
+  name,
+  placeholder,
+}: SelectProps) {
+  return (
+    <SelectContext.Provider value={{ placeholder }}>
+      <BaseSelect.Root
+        value={value}
+        defaultValue={defaultValue}
+        onValueChange={onValueChange}
+        open={open}
+        defaultOpen={defaultOpen}
+        onOpenChange={onOpenChange}
+        disabled={disabled}
+        required={required}
+        name={name}
+      >
+        {children}
+      </BaseSelect.Root>
+    </SelectContext.Provider>
+  );
+}
+
+function SelectTrigger({ children, placeholder, className }: SelectTriggerProps) {
+  const context = React.useContext(SelectContext);
+  const placeholderText = placeholder ?? context.placeholder;
+
+  const classes = [styles.trigger, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseSelect.Trigger className={classes}>
+      {children ?? (
+        <>
+          <BaseSelect.Value placeholder={placeholderText} className={styles.value} />
+          <BaseSelect.Icon className={styles.icon}>
+            <ChevronDownIcon />
+          </BaseSelect.Icon>
+        </>
+      )}
+    </BaseSelect.Trigger>
+  );
+}
+
+function SelectContent({
+  children,
+  className,
+  sideOffset = 4,
+  align = 'start',
+}: SelectContentProps) {
+  const popupClasses = [styles.popup, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseSelect.Portal>
+      <BaseSelect.Positioner
+        sideOffset={sideOffset}
+        align={align}
+        className={styles.positioner}
+      >
+        <BaseSelect.Popup className={popupClasses}>
+          {children}
+        </BaseSelect.Popup>
+      </BaseSelect.Positioner>
+    </BaseSelect.Portal>
+  );
+}
+
+function SelectItem({ children, value, disabled, className }: SelectItemProps) {
+  const classes = [styles.item, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseSelect.Item value={value} disabled={disabled} className={classes}>
+      <BaseSelect.ItemText>{children}</BaseSelect.ItemText>
+      <BaseSelect.ItemIndicator className={styles.itemIndicator}>
+        <CheckIcon />
+      </BaseSelect.ItemIndicator>
+    </BaseSelect.Item>
+  );
+}
+
+function SelectGroup({ children, className }: SelectGroupProps) {
+  const classes = [styles.group, className].filter(Boolean).join(' ');
+  return <BaseSelect.Group className={classes}>{children}</BaseSelect.Group>;
+}
+
+function SelectGroupLabel({ children, className }: SelectGroupLabelProps) {
+  const classes = [styles.groupLabel, className].filter(Boolean).join(' ');
+  return <BaseSelect.GroupLabel className={classes}>{children}</BaseSelect.GroupLabel>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Select = Object.assign(SelectRoot, {
+  Trigger: SelectTrigger,
+  Content: SelectContent,
+  Item: SelectItem,
+  Group: SelectGroup,
+  GroupLabel: SelectGroupLabel,
+});
+
+// Re-export individual components
+export {
+  SelectRoot,
+  SelectTrigger,
+  SelectContent,
+  SelectItem,
+  SelectGroup,
+  SelectGroupLabel,
+};