@structuralists/scaffolding 0.0.1

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

@@ -0,0 +1,55 @@
+import { cx } from '../../../utils';
+import { Tooltip } from '../../Overlays/Tooltip';
+import type {
+  IconButtonProps,
+  IconButtonSize,
+  IconButtonVariant,
+} from './types';
+import styles from './styles.module.css';
+
+const VARIANT_MAP: Record<IconButtonVariant, string> = {
+  ghost: styles.ghost,
+  solid: styles.solid,
+  danger: styles.danger,
+};
+
+const SIZE_MAP: Record<IconButtonSize, string> = {
+  small: styles.small,
+  medium: styles.medium,
+};
+
+export const IconButton = (props: IconButtonProps) => {
+  const {
+    children,
+    ariaLabel,
+    tooltip,
+    variant = 'ghost',
+    size = 'medium',
+    type = 'button',
+    onClick,
+    disabled,
+    autoFocus,
+    ref,
+  } = props;
+
+  const button = (
+    <button
+      ref={ref}
+      type={type}
+      aria-label={ariaLabel}
+      className={cx(styles.button, VARIANT_MAP[variant], SIZE_MAP[size])}
+      onClick={onClick}
+      disabled={disabled}
+      autoFocus={autoFocus}
+    >
+      {children}
+    </button>
+  );
+
+  if (tooltip) {
+    return <Tooltip label={tooltip}>{button}</Tooltip>;
+  }
+  return button;
+};
+
+export type { IconButtonProps, IconButtonVariant, IconButtonSize };

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

@@ -0,0 +1,61 @@
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--ui-radius);
+  cursor: pointer;
+  color: var(--ui-foreground);
+}
+
+.button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: 1px;
+}
+
+.small {
+  width: 24px;
+  height: 24px;
+}
+
+.medium {
+  width: 32px;
+  height: 32px;
+}
+
+.ghost {
+  background-color: transparent;
+  border-color: transparent;
+  color: var(--ui-muted);
+}
+
+.ghost:hover:not(:disabled) {
+  background-color: var(--ui-background-3);
+  color: var(--ui-foreground);
+}
+
+.solid {
+  background-color: var(--ui-background-0);
+  border-color: var(--ui-border);
+  color: var(--ui-foreground);
+}
+
+.solid:hover:not(:disabled) {
+  background-color: var(--ui-background-1);
+}
+
+.danger {
+  background-color: transparent;
+  border-color: transparent;
+  color: var(--ui-danger);
+}
+
+.danger:hover:not(:disabled) {
+  background-color: var(--ui-background-3);
+}

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

@@ -0,0 +1,23 @@
+import type { MouseEventHandler, ReactNode, Ref } from 'react';
+
+export type IconButtonVariant = 'ghost' | 'solid' | 'danger';
+export type IconButtonSize = 'small' | 'medium';
+export type IconButtonType = 'button' | 'submit' | 'reset';
+
+export type IconButtonProps = {
+  /** The icon to render. Typically an inline SVG sized to ~16px. */
+  children: ReactNode;
+  /** Required. Icon-only buttons have no text, so an accessible name must
+   *  be supplied explicitly. */
+  ariaLabel: string;
+  /** Optional tooltip text shown on hover/focus. Independent of `ariaLabel`
+   *  so screen-reader text and visual hint can differ. */
+  tooltip?: string;
+  variant?: IconButtonVariant;
+  size?: IconButtonSize;
+  type?: IconButtonType;
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  ref?: Ref<HTMLButtonElement>;
+};

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

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Input } from './index';
+
+const meta: Meta<typeof Input> = {
+  title: 'Forms/Input',
+  component: Input,
+  argTypes: {
+    size: { control: 'inline-radio', options: ['small', 'medium'] },
+  },
+  args: { placeholder: 'Enter text...', size: 'medium' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Input>;
+
+export const Default: Story = {};
+
+export const Small: Story = { args: { size: 'small' } };
+
+export const Disabled: Story = {
+  args: { disabled: true, defaultValue: 'Some value' },
+};

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

@@ -0,0 +1,42 @@
+import type { InputProps, InputSize } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const SIZE_MAP: Record<InputSize, string> = {
+  small: styles.small,
+  medium: styles.medium,
+};
+
+export const Input = (props: InputProps) => {
+  const {
+    type = 'text',
+    size = 'medium',
+    value,
+    defaultValue,
+    onChange,
+    placeholder,
+    required,
+    autoFocus,
+    disabled,
+    id,
+    name,
+  } = props;
+
+  return (
+    <input
+      type={type}
+      className={cx(styles.input, SIZE_MAP[size])}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={onChange}
+      placeholder={placeholder}
+      required={required}
+      autoFocus={autoFocus}
+      disabled={disabled}
+      id={id}
+      name={name}
+    />
+  );
+};
+
+export type { InputProps };

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

@@ -0,0 +1,30 @@
+.input {
+  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);
+  width: 100%;
+  line-height: var(--ui-line-height);
+}
+
+.input:focus {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+  border-color: var(--ui-accent);
+}
+
+.input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.small {
+  font-size: var(--ui-text-small);
+  padding: 4px 8px;
+}
+
+.medium {
+  font-size: var(--ui-text-medium);
+  padding: 6px 10px;
+}

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

@@ -0,0 +1,18 @@
+import type { ChangeEventHandler } from 'react';
+
+export type InputSize = 'small' | 'medium';
+export type InputType = 'text' | 'email' | 'password';
+
+export type InputProps = {
+  type?: InputType;
+  size?: InputSize;
+  value?: string;
+  defaultValue?: string;
+  onChange?: ChangeEventHandler<HTMLInputElement>;
+  placeholder?: string;
+  required?: boolean;
+  autoFocus?: boolean;
+  disabled?: boolean;
+  id?: string;
+  name?: string;
+};

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

@@ -0,0 +1,41 @@
+import type { SearchInputProps, SearchInputSize } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const SIZE_MAP: Record<SearchInputSize, string> = {
+  small: styles.small,
+  medium: styles.medium,
+};
+
+export const SearchInput = (props: SearchInputProps) => {
+  const {
+    label,
+    size = 'medium',
+    value,
+    defaultValue,
+    onChange,
+    placeholder,
+    disabled,
+    autoFocus,
+    id,
+    name,
+  } = props;
+
+  return (
+    <input
+      type="search"
+      aria-label={label}
+      className={cx(styles.input, SIZE_MAP[size])}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={onChange}
+      placeholder={placeholder}
+      disabled={disabled}
+      autoFocus={autoFocus}
+      id={id}
+      name={name}
+    />
+  );
+};
+
+export type { SearchInputProps };

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

@@ -0,0 +1,30 @@
+.input {
+  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);
+  width: 100%;
+}
+
+.input:focus {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+  border-color: var(--ui-accent);
+}
+
+.input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.small {
+  font-size: var(--ui-text-small);
+  padding: 4px 8px;
+}
+
+.medium {
+  font-size: var(--ui-text-medium);
+  padding: 6px 10px;
+}

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

@@ -0,0 +1,17 @@
+import type { ChangeEventHandler } from 'react';
+
+export type SearchInputSize = 'small' | 'medium';
+
+export type SearchInputProps = {
+  /** Accessible name for the unlabeled search input. Becomes the aria-label. */
+  label: string;
+  size?: SearchInputSize;
+  value?: string;
+  defaultValue?: string;
+  onChange?: ChangeEventHandler<HTMLInputElement>;
+  placeholder?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  id?: string;
+  name?: string;
+};

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

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { MultiSelect } from './index';
+import { Field } from '../../Field';
+import { Stack } from '../../../Layout/Stack';
+import { Text } from '../../../Content/Text';
+
+const meta: Meta<typeof MultiSelect> = {
+  title: 'Forms/MultiSelect',
+  component: MultiSelect,
+};
+
+export default meta;
+type Story = StoryObj<typeof MultiSelect>;
+
+type Tag = 'design' | 'engineering' | 'product' | 'ops' | 'legal';
+
+const TAG_OPTIONS: { value: Tag; label: string }[] = [
+  { value: 'design', label: 'Design' },
+  { value: 'engineering', label: 'Engineering' },
+  { value: 'product', label: 'Product' },
+  { value: 'ops', label: 'Ops' },
+  { value: 'legal', label: 'Legal' },
+];
+
+export const Basic: Story = {
+  render: () => {
+    const [values, setValues] = useState<Tag[]>(['engineering']);
+    return (
+      <div style={{ padding: 32, maxWidth: 360 }}>
+        <Field label="Tags">
+          <MultiSelect<Tag>
+            options={TAG_OPTIONS}
+            values={values}
+            onChange={setValues}
+            placeholder="Pick some tags…"
+          />
+        </Field>
+        <div style={{ marginTop: 16 }}>
+          <Text size="small" isMuted>
+            Selected: {values.join(', ') || '—'}
+          </Text>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Empty: Story = {
+  render: () => {
+    const [values, setValues] = useState<Tag[]>([]);
+    return (
+      <div style={{ padding: 32, maxWidth: 360 }}>
+        <MultiSelect<Tag>
+          options={TAG_OPTIONS}
+          values={values}
+          onChange={setValues}
+          placeholder="Pick some tags…"
+        />
+      </div>
+    );
+  },
+};
+
+export const CustomSummary: Story = {
+  render: () => {
+    const [values, setValues] = useState<Tag[]>(['design', 'product']);
+    return (
+      <div style={{ padding: 32, maxWidth: 360 }}>
+        <Stack direction="column" gap={2}>
+          <Text size="small" isMuted>
+            `renderSummary` replaces the "N selected" default.
+          </Text>
+          <MultiSelect<Tag>
+            options={TAG_OPTIONS}
+            values={values}
+            onChange={setValues}
+            renderSummary={(selected) =>
+              selected.map((s) => s.label).join(', ')
+            }
+          />
+        </Stack>
+      </div>
+    );
+  },
+};
+
+export const Small: Story = {
+  render: () => {
+    const [values, setValues] = useState<Tag[]>([]);
+    return (
+      <div style={{ padding: 32, maxWidth: 240 }}>
+        <MultiSelect<Tag>
+          options={TAG_OPTIONS}
+          values={values}
+          onChange={setValues}
+          size="small"
+          placeholder="Tags…"
+        />
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ padding: 32, maxWidth: 360 }}>
+      <MultiSelect<Tag>
+        options={TAG_OPTIONS}
+        values={['design']}
+        onChange={() => {}}
+        isDisabled
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,74 @@
+import { useRef, useState } from 'react';
+import { Popover } from '../../../Overlays/Popover';
+import { OptionList } from '../internal/OptionList';
+import { SelectTrigger } from '../internal/SelectTrigger';
+import type { MultiSelectProps } from './types';
+
+const defaultSummary = <T extends string>(selected: { value: T; label: string }[]) =>
+  selected.length === 1 ? selected[0]!.label : `${selected.length} selected`;
+
+export const MultiSelect = <T extends string,>({
+  options,
+  values,
+  onChange,
+  size = 'medium',
+  isDisabled,
+  placeholder = 'Select…',
+  renderSummary = defaultSummary,
+  ariaLabel,
+}: MultiSelectProps<T>) => {
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+
+  const selectedSet = new Set(values);
+  const selectedOptions = options.filter((o) => selectedSet.has(o.value));
+  const hasSelection = selectedOptions.length > 0;
+  const firstSelectedIndex = hasSelection
+    ? options.findIndex((o) => selectedSet.has(o.value))
+    : 0;
+
+  const close = () => setIsOpen(false);
+  const toggle = () => setIsOpen((v) => !v);
+  const commitToggle = (next: T) => {
+    const isCurrentlySelected = selectedSet.has(next);
+    const nextValues = isCurrentlySelected
+      ? values.filter((v) => v !== next)
+      : [...values, next];
+    onChange(nextValues);
+  };
+
+  return (
+    <>
+      <SelectTrigger
+        ref={triggerRef}
+        size={size}
+        isOpen={isOpen}
+        isDisabled={isDisabled}
+        isPlaceholder={!hasSelection}
+        onToggle={toggle}
+        ariaLabel={ariaLabel}
+      >
+        {hasSelection ? renderSummary(selectedOptions) : placeholder}
+      </SelectTrigger>
+      <Popover
+        anchorRef={triggerRef}
+        isOpen={isOpen}
+        onClose={close}
+        ariaLabel={ariaLabel ?? 'Select options'}
+        matchAnchorWidth
+        hasBodyPadding={false}
+      >
+        <OptionList<T>
+          options={options}
+          isSelected={(v) => selectedSet.has(v)}
+          onCommit={commitToggle}
+          initialFocusIndex={firstSelectedIndex}
+          indicator="checkbox"
+          ariaMultiSelectable
+        />
+      </Popover>
+    </>
+  );
+};
+
+export type { MultiSelectProps };

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

@@ -0,0 +1,15 @@
+import type { SelectOption } from '../internal/OptionList';
+import type { SelectSize } from '../internal/SelectTrigger';
+
+export type MultiSelectProps<T extends string = string> = {
+  options: SelectOption<T>[];
+  values: T[];
+  onChange: (values: T[]) => void;
+  size?: SelectSize;
+  isDisabled?: boolean;
+  /** Displayed when `values` is empty. */
+  placeholder?: string;
+  /** Custom summary builder when selections exist. Defaults to "N selected". */
+  renderSummary?: (selected: SelectOption<T>[]) => string;
+  ariaLabel?: string;
+};