@structuralists/scaffolding 0.0.1

package/src/components/Forms/Select/SingleSelect/SingleSelect.stories.tsx

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { SingleSelect } from './index';
+import { Button } from '../../Button';
+import { Field } from '../../Field';
+import { MediumModal } from '../../../Modals';
+import { Stack } from '../../../Layout/Stack';
+import { Text } from '../../../Content/Text';
+import { Toggle } from '../../../../storybook';
+
+const meta: Meta<typeof SingleSelect> = {
+  title: 'Forms/SingleSelect',
+  component: SingleSelect,
+};
+
+export default meta;
+type Story = StoryObj<typeof SingleSelect>;
+
+type Period = 'weekly' | 'monthly' | 'quarterly' | 'annual';
+
+const PERIOD_OPTIONS: { value: Period; label: string }[] = [
+  { value: 'weekly', label: 'Weekly' },
+  { value: 'monthly', label: 'Monthly' },
+  { value: 'quarterly', label: 'Quarterly' },
+  { value: 'annual', label: 'Annual' },
+];
+
+export const Basic: Story = {
+  render: () => {
+    const [value, setValue] = useState<Period>('monthly');
+    return (
+      <div style={{ padding: 32, maxWidth: 360 }}>
+        <Field label="Period">
+          <SingleSelect<Period>
+            options={PERIOD_OPTIONS}
+            value={value}
+            onChange={setValue}
+          />
+        </Field>
+        <div style={{ marginTop: 16 }}>
+          <Text size="small" isMuted>
+            Selected: {value}
+          </Text>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Unselected: Story = {
+  render: () => {
+    const [value, setValue] = useState<Period | null>(null);
+    return (
+      <div style={{ padding: 32, maxWidth: 360 }}>
+        <Field label="Period">
+          <SingleSelect<Period>
+            options={PERIOD_OPTIONS}
+            value={value}
+            onChange={setValue}
+            placeholder="Pick a cadence…"
+          />
+        </Field>
+      </div>
+    );
+  },
+};
+
+export const Small: Story = {
+  render: () => {
+    const [value, setValue] = useState<Period>('weekly');
+    return (
+      <div style={{ padding: 32, maxWidth: 240 }}>
+        <SingleSelect<Period>
+          options={PERIOD_OPTIONS}
+          value={value}
+          onChange={setValue}
+          size="small"
+        />
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ padding: 32, maxWidth: 360 }}>
+      <SingleSelect<Period>
+        options={PERIOD_OPTIONS}
+        value="monthly"
+        onChange={() => {}}
+        isDisabled
+      />
+    </div>
+  ),
+};
+
+// Repro for the dropdown-inside-modal bug: the SingleSelect's popover panel
+// is portaled to document.body, but MediumModal uses a native <dialog> opened
+// via showModal(), which renders in the browser's top layer above all normal
+// DOM regardless of z-index. The panel ends up *behind* the dialog and is
+// invisible even though the trigger reads as "open".
+export const InsideModal: Story = {
+  render: () => {
+    const [value, setValue] = useState<Period | null>(null);
+    return (
+      <Toggle defaultOn>
+        {({ isOn, on, off }) => (
+          <>
+            <Button onClick={on}>New workspace…</Button>
+            <MediumModal
+              isOpen={isOn}
+              onClose={off}
+              title="New workspace"
+              footer={
+                <>
+                  <Button onClick={off}>Cancel</Button>
+                  <Button variant="primary" onClick={off}>Create</Button>
+                </>
+              }
+            >
+              <Stack gap={3}>
+                <Field label="Definition">
+                  <SingleSelect<Period>
+                    options={PERIOD_OPTIONS}
+                    value={value}
+                    onChange={setValue}
+                    placeholder="Pick a def…"
+                  />
+                </Field>
+              </Stack>
+            </MediumModal>
+          </>
+        )}
+      </Toggle>
+    );
+  },
+};
+
+export const Long: Story = {
+  render: () => {
+    const [value, setValue] = useState<string>('apple');
+    const options = [
+      { value: 'apple', label: 'Apple' },
+      { value: 'banana', label: 'Banana' },
+      { value: 'cherry', label: 'Cherry' },
+      { value: 'durian', label: 'Durian' },
+      { value: 'elderberry', label: 'Elderberry' },
+      { value: 'fig', label: 'Fig' },
+      { value: 'grape', label: 'Grape' },
+      { value: 'honeydew', label: 'Honeydew' },
+      { value: 'jackfruit', label: 'Jackfruit' },
+      { value: 'kiwi', label: 'Kiwi' },
+      { value: 'lemon', label: 'Lemon' },
+      { value: 'mango', label: 'Mango' },
+      { value: 'nectarine', label: 'Nectarine' },
+      { value: 'orange', label: 'Orange' },
+      { value: 'papaya', label: 'Papaya' },
+    ];
+    return (
+      <div style={{ padding: 32, maxWidth: 360 }}>
+        <Stack direction="column" gap={2}>
+          <Text size="small" isMuted>
+            Scrolls internally when options exceed the list's max height.
+          </Text>
+          <SingleSelect
+            options={options}
+            value={value}
+            onChange={setValue}
+          />
+        </Stack>
+      </div>
+    );
+  },
+};

package/src/components/Forms/Select/SingleSelect/index.tsx

@@ -0,0 +1,62 @@
+import { useRef, useState } from 'react';
+import { Popover } from '../../../Overlays/Popover';
+import { OptionList } from '../internal/OptionList';
+import { SelectTrigger } from '../internal/SelectTrigger';
+import type { SingleSelectProps } from './types';
+
+export const SingleSelect = <T extends string,>({
+  options,
+  value,
+  onChange,
+  size = 'medium',
+  isDisabled,
+  placeholder = 'Select…',
+  ariaLabel,
+}: SingleSelectProps<T>) => {
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+
+  const selectedIndex = options.findIndex((o) => o.value === value);
+  const selected = selectedIndex >= 0 ? options[selectedIndex] : undefined;
+
+  const close = () => setIsOpen(false);
+  const toggle = () => setIsOpen((v) => !v);
+  const commit = (next: T) => {
+    onChange(next);
+    close();
+  };
+
+  return (
+    <>
+      <SelectTrigger
+        ref={triggerRef}
+        size={size}
+        isOpen={isOpen}
+        isDisabled={isDisabled}
+        isPlaceholder={!selected}
+        onToggle={toggle}
+        ariaLabel={ariaLabel}
+      >
+        {selected?.label ?? placeholder}
+      </SelectTrigger>
+      <Popover
+        anchorRef={triggerRef}
+        isOpen={isOpen}
+        onClose={close}
+        ariaLabel={ariaLabel ?? 'Select an option'}
+        matchAnchorWidth
+        hasBodyPadding={false}
+      >
+        <OptionList<T>
+          options={options}
+          isSelected={(v) => v === value}
+          onCommit={commit}
+          initialFocusIndex={selectedIndex >= 0 ? selectedIndex : 0}
+          indicator="check"
+        />
+      </Popover>
+    </>
+  );
+};
+
+export type { SingleSelectProps };

package/src/components/Forms/Select/SingleSelect/types.ts

@@ -0,0 +1,12 @@
+import type { SelectOption } from '../internal/OptionList';
+import type { SelectSize } from '../internal/SelectTrigger';
+
+export type SingleSelectProps<T extends string = string> = {
+  options: SelectOption<T>[];
+  value: T | null;
+  onChange: (value: T) => void;
+  size?: SelectSize;
+  isDisabled?: boolean;
+  placeholder?: string;
+  ariaLabel?: string;
+};

package/src/components/Forms/Select/index.ts

@@ -0,0 +1,4 @@
+export { SingleSelect, type SingleSelectProps } from './SingleSelect';
+export { MultiSelect, type MultiSelectProps } from './MultiSelect';
+export type { SelectOption } from './internal/OptionList';
+export type { SelectSize } from './internal/SelectTrigger';

package/src/components/Forms/Select/internal/OptionList.tsx

@@ -0,0 +1,124 @@
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type KeyboardEvent,
+} from 'react';
+import { cx } from '../../../../utils';
+import styles from './styles.module.css';
+
+export type SelectOption<T extends string> = {
+  value: T;
+  label: string;
+};
+
+export type OptionListIndicator = 'check' | 'checkbox' | 'none';
+
+export type OptionListProps<T extends string> = {
+  options: SelectOption<T>[];
+  isSelected: (value: T) => boolean;
+  onCommit: (value: T) => void;
+  /** How each row signals its selected state.
+   *  - `check`: a ✓ appears on the selected row (SingleSelect default).
+   *  - `checkbox`: each row has a checkbox square that fills on selection (MultiSelect).
+   *  - `none`: no leading indicator. */
+  indicator?: OptionListIndicator;
+  /** Initial focus index — typically the index of the (first) selected value. */
+  initialFocusIndex?: number;
+  ariaMultiSelectable?: boolean;
+};
+
+const renderIndicator = (variant: OptionListIndicator, isSelected: boolean) => {
+  if (variant === 'none') return null;
+  if (variant === 'check') {
+    return (
+      <span className={styles.indicator}>{isSelected ? '✓' : null}</span>
+    );
+  }
+  return (
+    <span className={styles.indicator}>
+      <span
+        className={cx(styles.checkbox, isSelected && styles.checkboxChecked)}
+      >
+        {isSelected ? '✓' : null}
+      </span>
+    </span>
+  );
+};
+
+export const OptionList = <T extends string,>({
+  options,
+  isSelected,
+  onCommit,
+  indicator = 'check',
+  initialFocusIndex = 0,
+  ariaMultiSelectable,
+}: OptionListProps<T>) => {
+  const listRef = useRef<HTMLDivElement>(null);
+  const listId = useId();
+  const [focusIndex, setFocusIndex] = useState(() => {
+    if (options.length === 0) return 0;
+    return Math.min(Math.max(initialFocusIndex, 0), options.length - 1);
+  });
+
+  useEffect(() => {
+    listRef.current?.focus();
+  }, []);
+
+  const handleKey = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (options.length === 0) return;
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setFocusIndex((i) => (i + 1) % options.length);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setFocusIndex((i) => (i - 1 + options.length) % options.length);
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      setFocusIndex(0);
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      setFocusIndex(options.length - 1);
+    } else if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      const focused = options[focusIndex];
+      if (focused) onCommit(focused.value);
+    }
+  };
+
+  const activeOptionId =
+    options.length > 0 ? `${listId}-${focusIndex}` : undefined;
+
+  return (
+    <div
+      ref={listRef}
+      role="listbox"
+      tabIndex={0}
+      aria-multiselectable={ariaMultiSelectable}
+      aria-activedescendant={activeOptionId}
+      className={styles.list}
+      onKeyDown={handleKey}
+    >
+      {options.map((option, i) => {
+        const { value, label } = option;
+        const selected = isSelected(value);
+        const focused = i === focusIndex;
+        return (
+          <div
+            key={value}
+            id={`${listId}-${i}`}
+            role="option"
+            aria-selected={selected}
+            className={cx(styles.option, focused && styles.isFocused)}
+            onMouseEnter={() => setFocusIndex(i)}
+            onClick={() => onCommit(value)}
+          >
+            {renderIndicator(indicator, selected)}
+            <span className={styles.optionLabel}>{label}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+};

package/src/components/Forms/Select/internal/SelectTrigger.tsx

@@ -0,0 +1,60 @@
+import type { ReactNode, Ref } from 'react';
+import { cx } from '../../../../utils';
+import styles from './styles.module.css';
+
+export type SelectSize = 'small' | 'medium';
+
+export type SelectTriggerProps = {
+  children: ReactNode;
+  size?: SelectSize;
+  isOpen: boolean;
+  isDisabled?: boolean;
+  isPlaceholder?: boolean;
+  onToggle: () => void;
+  ariaLabel?: string;
+  ref?: Ref<HTMLButtonElement>;
+};
+
+const SIZE_MAP: Record<SelectSize, string> = {
+  small: styles.small,
+  medium: styles.medium,
+};
+
+export const SelectTrigger = (props: SelectTriggerProps) => {
+  const {
+    children,
+    size = 'medium',
+    isOpen,
+    isDisabled,
+    isPlaceholder,
+    onToggle,
+    ariaLabel,
+    ref,
+  } = props;
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      className={cx(
+        styles.trigger,
+        SIZE_MAP[size],
+        isOpen && styles.isOpen,
+      )}
+      aria-haspopup="listbox"
+      aria-expanded={isOpen}
+      aria-label={ariaLabel}
+      disabled={isDisabled}
+      onClick={onToggle}
+    >
+      <span
+        className={cx(styles.triggerLabel, isPlaceholder && styles.isPlaceholder)}
+      >
+        {children}
+      </span>
+      <span className={styles.chevron} aria-hidden="true">
+        ▾
+      </span>
+    </button>
+  );
+};

package/src/components/Forms/Select/internal/styles.module.css

@@ -0,0 +1,122 @@
+.trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ui-space-2);
+  width: 100%;
+  font-family: var(--ui-font);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  background-color: var(--ui-background-0);
+  color: var(--ui-foreground);
+  line-height: var(--ui-line-height);
+  cursor: pointer;
+  text-align: left;
+}
+
+.trigger:focus-visible {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+  border-color: var(--ui-accent);
+}
+
+.trigger:hover:not(:disabled) {
+  background-color: var(--ui-background-0-offset);
+}
+
+.trigger:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.isOpen {
+  border-color: var(--ui-accent);
+}
+
+.small {
+  font-size: var(--ui-text-small);
+  padding: 4px 8px;
+}
+
+.medium {
+  font-size: var(--ui-text-medium);
+  padding: 6px 10px;
+}
+
+.triggerLabel {
+  flex: 1 1 auto;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.isPlaceholder {
+  color: var(--ui-muted);
+}
+
+.chevron {
+  color: var(--ui-muted);
+  font-size: var(--ui-text-xsmall);
+  flex: 0 0 auto;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  outline: none;
+  max-height: 280px;
+  overflow-y: auto;
+  padding: var(--ui-space-1) 0;
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  padding: var(--ui-space-1) var(--ui-space-3);
+  font-size: var(--ui-text-small);
+  color: var(--ui-foreground);
+  cursor: pointer;
+  user-select: none;
+  white-space: nowrap;
+}
+
+.isFocused {
+  background-color: var(--ui-background-1);
+}
+
+.indicator {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  flex: 0 0 auto;
+  color: var(--ui-muted);
+}
+
+.optionLabel {
+  flex: 1 1 auto;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.checkbox {
+  width: 14px;
+  height: 14px;
+  border: 1px solid var(--ui-border);
+  border-radius: 3px;
+  background-color: var(--ui-background-0);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+}
+
+.checkboxChecked {
+  background-color: var(--ui-accent);
+  border-color: var(--ui-accent);
+  color: var(--ui-background-0);
+  font-size: 11px;
+  line-height: 1;
+}

package/src/components/Forms/Textarea/Textarea.stories.tsx

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Textarea } from './index';
+
+const meta: Meta<typeof Textarea> = {
+  title: 'Forms/Textarea',
+  component: Textarea,
+  args: { placeholder: 'Write something...', rows: 4 },
+};
+
+export default meta;
+type Story = StoryObj<typeof Textarea>;
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  args: { disabled: true, defaultValue: 'Read-only content.' },
+};
+
+export const AutoResize: Story = {
+  args: {
+    isAutoResize: true,
+    rows: 2,
+    placeholder: 'Type — the box grows to fit…',
+  },
+};

package/src/components/Forms/Textarea/index.tsx

@@ -0,0 +1,48 @@
+import { cx } from '../../../utils';
+import type { TextareaProps } from './types';
+import styles from './styles.module.css';
+
+export const Textarea = (props: TextareaProps) => {
+  const {
+    value,
+    defaultValue,
+    onChange,
+    rows = 2,
+    placeholder,
+    disabled,
+    required,
+    autoFocus,
+    id,
+    name,
+    isAutoResize,
+  } = props;
+
+  // field-sizing: content doesn't enforce a rows-based floor on its own,
+  // so compute min-height from `rows` and apply it inline when isAutoResize.
+  // Formula: rows × line-height × font-size + vertical padding + border.
+  // With .textarea's padding (8px top+bottom = 16px) + 1px border × 2 = 18px.
+  const style = isAutoResize
+    ? {
+        minHeight: `calc(var(--ui-text-medium) * var(--ui-line-height) * ${rows} + 18px)`,
+      }
+    : undefined;
+
+  return (
+    <textarea
+      className={cx(styles.textarea, isAutoResize && styles.autoResize)}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={onChange}
+      rows={rows}
+      placeholder={placeholder}
+      disabled={disabled}
+      required={required}
+      autoFocus={autoFocus}
+      id={id}
+      name={name}
+      style={style}
+    />
+  );
+};
+
+export type { TextareaProps };

package/src/components/Forms/Textarea/styles.module.css

@@ -0,0 +1,34 @@
+.textarea {
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-medium);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  background-color: var(--ui-background-0);
+  color: var(--ui-foreground);
+  padding: 8px 10px;
+  width: 100%;
+  min-height: 80px;
+  resize: vertical;
+  line-height: var(--ui-line-height);
+}
+
+.textarea:focus {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+  border-color: var(--ui-accent);
+}
+
+.textarea:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.autoResize {
+  /* Modern CSS: textarea grows to fit content, shrinks when content shrinks.
+     The manual resize handle goes away since it'd fight the intrinsic sizing.
+     min-height is computed from `rows` and applied inline in the component
+     (field-sizing: content doesn't enforce a rows-based floor on its own).
+     Browser support: Chrome 123+, Safari 17.4+, Firefox 131+. */
+  field-sizing: content;
+  resize: none;
+}

package/src/components/Forms/Textarea/types.ts

@@ -0,0 +1,24 @@
+import type { ChangeEventHandler } from 'react';
+
+export type TextareaProps = {
+  value?: string;
+  defaultValue?: string;
+  onChange?: ChangeEventHandler<HTMLTextAreaElement>;
+  rows?: number;
+  placeholder?: string;
+  disabled?: boolean;
+  required?: boolean;
+  autoFocus?: boolean;
+  id?: string;
+  name?: string;
+  /**
+   * Grow the textarea to fit its content. The manual resize handle is
+   * removed. Uses CSS `field-sizing: content` (Chrome 123+, Safari 17.4+)
+   * with no JS fallback — fine for modern browsers and this app's scope.
+   *
+   * `rows` is the minimum visible rows (the floor). An empty textarea
+   * with `rows={3}` renders at 3 rows tall; content longer than that
+   * grows the box.
+   */
+  isAutoResize?: boolean;
+};