@scalepad/ui 0.1.0

package/src/components/MetricDisplay/MetricDisplay.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+
+import { Flex } from '@mantine/core';
+
+import { Text } from '../Typography/Text';
+import { Title } from '../Typography/Title';
+
+export interface MetricDisplayProps {
+  /**
+   * Label text to display above the metric value
+   */
+  label: string;
+  /**
+   * Metric value to display (can be string or React node)
+   */
+  value: ReactNode;
+  /**
+   * Size variant for the metric display
+   * - 'sm': heading4 variant with order 5 (smaller)
+   * - 'md': heading4 variant (default)
+   * - 'lg': heading3 variant (larger)
+   */
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/**
+ * MetricDisplay component
+ * Displays a metric with a label and value in a consistent format
+ * Used for KPIs, statistics, and other key metrics throughout the app
+ */
+export function MetricDisplay({
+  label,
+  value,
+  size = 'md',
+}: MetricDisplayProps) {
+  const titleVariantMap = {
+    sm: 'heading4',
+    md: 'heading4',
+    lg: 'heading3',
+  } as const;
+
+  return (
+    <Flex direction="column" gap="xs">
+      <Text variant="caption1.strong" c="text.subdued.default">
+        {label}
+      </Text>
+      <Title
+        variant={titleVariantMap[size]}
+        {...(size === 'sm' ? { order: 5 } : {})}
+      >
+        {value}
+      </Title>
+    </Flex>
+  );
+}

package/src/components/MetricDisplay/index.ts

@@ -0,0 +1 @@
+export { MetricDisplay, type MetricDisplayProps } from './MetricDisplay';

package/src/components/MultiSelect/MultiSelect.tsx

@@ -0,0 +1,278 @@
+import { forwardRef, useMemo } from 'react';
+
+import {
+  CheckIcon,
+  Combobox,
+  Group,
+  Input,
+  MultiSelect as MantineMultiSelect,
+  Pill,
+  PillsInput,
+  type MultiSelectProps as MantineMultiSelectProps,
+  useCombobox,
+} from '@mantine/core';
+import { useUncontrolled } from '@mantine/hooks';
+
+type ParsedOption = {
+  value: string;
+  label: string;
+  disabled?: boolean;
+};
+
+export interface MultiSelectProps extends MantineMultiSelectProps {
+  maxDisplayedItems?: number;
+}
+
+interface LimitedPillMultiSelectProps extends Omit<
+  MultiSelectProps,
+  'maxDisplayedItems'
+> {
+  maxDisplayedItems: number;
+}
+
+function parseOption(
+  item: string | { value: string; label?: string; disabled?: boolean },
+) {
+  if (typeof item === 'string') {
+    return { value: item, label: item };
+  }
+
+  return {
+    value: item.value,
+    label: item.label ?? item.value,
+    disabled: item.disabled,
+  };
+}
+
+function parseOptions(data: MantineMultiSelectProps['data']): ParsedOption[] {
+  if (!data) {
+    return [];
+  }
+
+  return data.flatMap(item => {
+    if (
+      typeof item === 'string' ||
+      ('value' in item && typeof item.value === 'string')
+    ) {
+      return [parseOption(item)];
+    }
+
+    if ('items' in item && Array.isArray(item.items)) {
+      return item.items.map(groupItem => parseOption(groupItem));
+    }
+
+    return [];
+  });
+}
+
+function getDisplayedValues(values: string[], maxDisplayedItems?: number) {
+  if (maxDisplayedItems == null) {
+    return values;
+  }
+
+  const normalizedMaxDisplayedItems = Math.max(1, maxDisplayedItems);
+
+  if (values.length <= normalizedMaxDisplayedItems) {
+    return values;
+  }
+
+  return values.slice(0, Math.max(0, normalizedMaxDisplayedItems - 1));
+}
+
+export const MultiSelect = forwardRef<HTMLInputElement, MultiSelectProps>(
+  ({ maxDisplayedItems, ...props }, ref) => {
+    if (maxDisplayedItems == null) {
+      return <MantineMultiSelect ref={ref} {...props} />;
+    }
+
+    return (
+      <LimitedPillMultiSelect
+        ref={ref}
+        maxDisplayedItems={maxDisplayedItems}
+        {...props}
+      />
+    );
+  },
+);
+
+MultiSelect.displayName = 'MultiSelect';
+
+const LimitedPillMultiSelect = forwardRef<
+  HTMLInputElement,
+  LimitedPillMultiSelectProps
+>(
+  (
+    {
+      maxDisplayedItems,
+      data,
+      value,
+      defaultValue,
+      onChange,
+      placeholder,
+      comboboxProps,
+      hidePickedOptions,
+      nothingFoundMessage = 'Nothing found',
+      disabled,
+      readOnly,
+      label,
+      description,
+      error,
+      required,
+      withAsterisk,
+      name,
+      id,
+      'aria-label': ariaLabel,
+    },
+    ref,
+  ) => {
+    const parsedOptions = useMemo(() => parseOptions(data), [data]);
+    const [selectedValues, setSelectedValues] = useUncontrolled({
+      value,
+      defaultValue,
+      finalValue: [],
+      onChange,
+    });
+
+    const combobox = useCombobox({
+      onDropdownClose: () => combobox.resetSelectedOption(),
+      onDropdownOpen: () => combobox.updateSelectedOptionIndex('active'),
+    });
+
+    const selectedLabelsByValue = useMemo(
+      () => new Map(parsedOptions.map(option => [option.value, option.label])),
+      [parsedOptions],
+    );
+
+    const availableOptions = hidePickedOptions
+      ? parsedOptions.filter(option => !selectedValues.includes(option.value))
+      : parsedOptions;
+
+    const displayedValues = getDisplayedValues(
+      selectedValues,
+      maxDisplayedItems,
+    );
+    const hiddenValuesCount = selectedValues.length - displayedValues.length;
+
+    function handleOptionSubmit(optionValue: string) {
+      if (disabled || readOnly) {
+        return;
+      }
+
+      setSelectedValues(
+        selectedValues.includes(optionValue)
+          ? selectedValues.filter(
+              selectedValue => selectedValue !== optionValue,
+            )
+          : [...selectedValues, optionValue],
+      );
+    }
+
+    const options = availableOptions.map(option => {
+      const isSelected = selectedValues.includes(option.value);
+
+      return (
+        <Combobox.Option
+          value={option.value}
+          key={option.value}
+          active={isSelected}
+          disabled={option.disabled}
+        >
+          <Group gap="sm">
+            {isSelected ? <CheckIcon size={12} /> : null}
+            <span>{option.label}</span>
+          </Group>
+        </Combobox.Option>
+      );
+    });
+
+    return (
+      <Input.Wrapper
+        label={label}
+        description={description}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+      >
+        <Combobox
+          store={combobox}
+          onOptionSubmit={handleOptionSubmit}
+          {...comboboxProps}
+        >
+          <Combobox.DropdownTarget>
+            <PillsInput
+              pointer={!disabled && !readOnly}
+              disabled={disabled}
+              onClick={() => {
+                if (!disabled && !readOnly) {
+                  combobox.toggleDropdown();
+                }
+              }}
+            >
+              <Pill.Group>
+                {selectedValues.length > 0 ? (
+                  <>
+                    {displayedValues.map(selectedValue => (
+                      <Pill
+                        key={selectedValue}
+                        withRemoveButton={!disabled && !readOnly}
+                        onRemove={() =>
+                          setSelectedValues(
+                            selectedValues.filter(
+                              valueItem => valueItem !== selectedValue,
+                            ),
+                          )
+                        }
+                      >
+                        {selectedLabelsByValue.get(selectedValue) ??
+                          selectedValue}
+                      </Pill>
+                    ))}
+                    {hiddenValuesCount > 0 ? (
+                      <Pill>+ {hiddenValuesCount} More</Pill>
+                    ) : null}
+                  </>
+                ) : (
+                  <Input.Placeholder>{placeholder}</Input.Placeholder>
+                )}
+
+                <Combobox.EventsTarget>
+                  <PillsInput.Field
+                    ref={ref}
+                    type="hidden"
+                    name={name}
+                    id={id}
+                    required={required}
+                    aria-label={
+                      ariaLabel ??
+                      (typeof label === 'string' ? label : undefined)
+                    }
+                    onBlur={() => combobox.closeDropdown()}
+                    onKeyDown={event => {
+                      if (
+                        event.key === 'Backspace' &&
+                        selectedValues.length > 0
+                      ) {
+                        event.preventDefault();
+                        setSelectedValues(selectedValues.slice(0, -1));
+                      }
+                    }}
+                  />
+                </Combobox.EventsTarget>
+              </Pill.Group>
+            </PillsInput>
+          </Combobox.DropdownTarget>
+
+          <Combobox.Dropdown>
+            {options.length > 0 ? (
+              <Combobox.Options>{options}</Combobox.Options>
+            ) : (
+              <div>{nothingFoundMessage}</div>
+            )}
+          </Combobox.Dropdown>
+        </Combobox>
+      </Input.Wrapper>
+    );
+  },
+);
+
+LimitedPillMultiSelect.displayName = 'LimitedPillMultiSelect';

package/src/components/MultiSelect/index.ts

@@ -0,0 +1,2 @@
+export { MultiSelect } from './MultiSelect';
+export type { MultiSelectProps } from './MultiSelect';

package/src/components/Notifications/Notifications.tsx

@@ -0,0 +1,12 @@
+import { Notifications as MantineNotifications } from '@mantine/notifications';
+
+/**
+ * Notifications container for toast messages.
+ * Renders the Mantine notifications provider; must be mounted inside MantineProvider.
+ * Typically included inside ThemeProvider so toasts can display app-wide.
+ */
+export function Notifications() {
+  return (
+    <MantineNotifications position="bottom-right" autoClose={4000} limit={5} />
+  );
+}

package/src/components/Notifications/README.md

@@ -0,0 +1,93 @@
+# Notifications
+
+Toast notifications via `showSuccessToast` / `showErrorToast` helpers, plus the `<Notifications />` provider that renders them.
+
+The helpers wrap `@mantine/notifications` with design-system defaults: green / red color, auto-close timing, and a styled-caption message body. The raw `notifications` object from Mantine is re-exported for cases the helpers don't cover, but new code should reach for the helpers.
+
+## Quick Start
+
+```tsx
+import { showSuccessToast, showErrorToast } from '@scalepad/ui';
+
+// Plain success / error
+showSuccessToast('User moved to department');
+showErrorToast('Failed to update approval status.');
+
+// With a custom title
+showSuccessToast('Foo was removed.', { title: 'Initiative deleted' });
+
+// With a retry action (auto-close disables so the user can click)
+showErrorToast('Could not update completion status.', {
+  title: 'Could not update completion status',
+  action: { label: 'Retry', onClick: retry },
+});
+
+// Override auto-close
+showSuccessToast('Saved.', { autoClose: 8000 });
+showSuccessToast('Saved.', { autoClose: false }); // persist until dismissed
+```
+
+## API
+
+### `showSuccessToast(message, options?)` / `showErrorToast(message, options?)`
+
+| Param     | Type                          | Description                                                                                       |
+| --------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| `message` | `string`                      | Body text rendered as a subdued caption.                                                          |
+| `options` | `string \| ShowToastOptions`  | Optional. Pass a string to set just the title (legacy form), or an options bag for richer toasts. |
+
+### `ShowToastOptions`
+
+| Field       | Type                | Default                                                                              | Description                                       |
+| ----------- | ------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| `title`     | `string`            | `'Success'` / `'Error'`                                                              | Heading text.                                     |
+| `action`    | `ShowToastAction`   | —                                                                                    | Optional action button rendered below the body.   |
+| `autoClose` | `number \| false`   | 4000 (success) / 5000 (error); `false` when `action` is present and not overridden   | Override auto-close. `false` keeps the toast up.  |
+
+### `ShowToastAction`
+
+| Field     | Type           | Description                          |
+| --------- | -------------- | ------------------------------------ |
+| `label`   | `string`       | Button label, e.g. `'Retry'`.        |
+| `onClick` | `() => void`   | Click handler.                       |
+
+## Defaults
+
+- **Auto-close**: 4s for success, 5s for error.
+- **Action toasts**: when `options.action` is present and `autoClose` is unspecified, the toast persists until dismissed so the user can click the action. Pass `autoClose: 8000` (or any number) to opt back into auto-close.
+- **Color**: green (success) / red (error) — encoded in the function name. Never pass color manually.
+
+## When to use what
+
+- **Plain string** — simple confirmation, single line. `showSuccessToast('Saved.')`.
+- **With `title`** — when heading and body convey different information ("Initiative deleted" / "Foo was removed.").
+- **With `action`** — recoverable errors where a one-click retry is meaningful (transient API failures). Persists by default.
+- **Raw `notifications.show()`** — escape hatch for cases the helpers don't cover (custom icons, loading states, multi-step UI). Prefer extending the helpers instead so call sites stay consistent.
+
+## Don't
+
+- Don't call `showSuccessToast` / `showErrorToast` inside a hook — toasting is a UI concern with no view context. See `apps/lm-web/.ai/rules/mutations.md` and `apps/lm-web/.ai/rules/error-handling.md` for the canonical pattern (hooks expose `error: Error | null`; components decide UX).
+- Don't bypass the helpers to pass `color` directly via raw `notifications.show()` for semantics — the function-name choice is the source of truth.
+
+## Provider
+
+Mount `<Notifications />` once at the app root (or in a shared overlays component):
+
+```tsx
+import { Notifications } from '@scalepad/ui';
+
+<App>
+  <Notifications />
+  {/* ... */}
+</App>
+```
+
+## More Examples
+
+See Storybook for interactive demos: `SuccessToast`, `ErrorToast`, `CustomTitles`, `WithRetryAction`.
+
+## Real-World Usage
+
+- `apps/lm-web/src/features/assessments/components/AssessmentDetail.tsx` — error toast with retry action.
+- `apps/lm-web/src/features/initiatives/components/initiativeOverflowMenu/InitiativeOverflowMenu.tsx` — success / error toasts in mutation callbacks.
+- `apps/amm-web/src/features/catalog/components/CatalogAppActionsCell.tsx` — string-only success / error toasts.

package/src/components/Notifications/index.ts

@@ -0,0 +1,4 @@
+export { Notifications } from './Notifications';
+export { showSuccessToast, showErrorToast } from './showToast';
+export type { ShowToastAction, ShowToastOptions } from './showToast';
+export { notifications } from '@mantine/notifications';

package/src/components/Notifications/showToast.tsx

@@ -0,0 +1,100 @@
+import type { ReactNode } from 'react';
+
+import { notifications } from '@mantine/notifications';
+
+import { Button } from '../Button';
+import { Stack } from '../DesignSystemPrimitives';
+import { Text } from '../Typography';
+
+export interface ShowToastAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface ShowToastOptions {
+  title?: string;
+  action?: ShowToastAction;
+  /** Override auto-close. Pass `false` to keep the toast until dismissed. */
+  autoClose?: number | false;
+}
+
+type SecondArg = string | ShowToastOptions;
+
+const SUCCESS_AUTO_CLOSE_MS = 4000;
+const ERROR_AUTO_CLOSE_MS = 5000;
+
+function normalizeOptions(secondArg?: SecondArg): ShowToastOptions {
+  if (secondArg == null) return {};
+  return typeof secondArg === 'string' ? { title: secondArg } : secondArg;
+}
+
+function buildBody(message: string, action?: ShowToastAction): ReactNode {
+  const caption = (
+    <Text variant="caption1" c="text.subdued.default">
+      {message}
+    </Text>
+  );
+
+  if (!action) {
+    return caption;
+  }
+
+  return (
+    <Stack gap="xs">
+      {caption}
+      <Button
+        type="button"
+        size="xs"
+        variant="outline"
+        onClick={action.onClick}
+      >
+        {action.label}
+      </Button>
+    </Stack>
+  );
+}
+
+function resolveAutoClose(
+  options: ShowToastOptions,
+  defaultMs: number,
+): number | false {
+  if (options.autoClose !== undefined) return options.autoClose;
+  // When an action is present, persist by default so the user can click it.
+  return options.action ? false : defaultMs;
+}
+
+/**
+ * Show a brief success toast (e.g. after create/update/delete).
+ * Pass a string as the second arg to set just the title, or an options bag
+ * for `action` / `autoClose` overrides.
+ */
+export function showSuccessToast(
+  message: string,
+  optionsOrTitle?: SecondArg,
+): void {
+  const options = normalizeOptions(optionsOrTitle);
+  notifications.show({
+    title: options.title ?? 'Success',
+    message: buildBody(message, options.action),
+    color: 'green',
+    autoClose: resolveAutoClose(options, SUCCESS_AUTO_CLOSE_MS),
+  });
+}
+
+/**
+ * Show a brief error toast.
+ * Pass a string as the second arg to set just the title, or an options bag
+ * for `action` (e.g. a Retry button) / `autoClose` overrides.
+ */
+export function showErrorToast(
+  message: string,
+  optionsOrTitle?: SecondArg,
+): void {
+  const options = normalizeOptions(optionsOrTitle);
+  notifications.show({
+    title: options.title ?? 'Error',
+    message: buildBody(message, options.action),
+    color: 'red',
+    autoClose: resolveAutoClose(options, ERROR_AUTO_CLOSE_MS),
+  });
+}

package/src/components/PropertyRow/PropertyRow.tsx

@@ -0,0 +1,96 @@
+import type { ReactNode } from 'react';
+
+import { Box, Group } from '../DesignSystemPrimitives';
+import { Text } from '../Typography';
+
+export interface PropertyRowProps {
+  /** Small icon (typically a 14px lucide glyph) rendered to the left of the label. */
+  icon: ReactNode;
+  /** Plain label text — e.g. "Client", "Due date", "Status". */
+  label: string;
+  /**
+   * Right-hand value content. Free-form so each property can render its
+   * own widget (chip, picker, plain text, link, etc.) without the row
+   * imposing structure.
+   */
+  children: ReactNode;
+  /**
+   * Override the fixed width of the label column. Defaults to 120 — the
+   * value the task drawer was designed against. Bump it for surfaces
+   * with longer label text so labels and values stay vertically aligned
+   * across rows.
+   */
+  labelWidth?: number;
+  /**
+   * Cross-axis alignment of the label column against the value content.
+   * Defaults to `'center'` for single-line values; pass `'flex-start'`
+   * when the value can grow vertically (e.g. a stack of assignees) so
+   * the label stays anchored to the first row of the value instead of
+   * floating in the middle.
+   */
+  align?: 'center' | 'flex-start';
+  /**
+   * When true, blocks interaction (e.g. while a mutation is in-flight).
+   */
+  disabled?: boolean;
+}
+
+const DEFAULT_LABEL_COLUMN_WIDTH = 120;
+const ROW_MIN_HEIGHT = 28;
+
+/**
+ * Two-column property row used by detail-drawer metadata stacks. Renders
+ * a subdued icon + label on the left and the consumer-provided value on
+ * the right. The label column is fixed-width (overridable via
+ * `labelWidth`) so labels stay vertically aligned across rows even when
+ * value widths vary — that lock-step alignment is what makes a stack of
+ * these rows scan as a coherent property table rather than a jagged list.
+ *
+ * Designed to be domain-agnostic: drawers in tasks, initiatives,
+ * playbooks, etc. should all reach for this primitive instead of
+ * re-implementing the same two-column layout.
+ */
+export function PropertyRow({
+  icon,
+  label,
+  children,
+  labelWidth = DEFAULT_LABEL_COLUMN_WIDTH,
+  align = 'center',
+  disabled = false,
+}: PropertyRowProps) {
+  return (
+    <Group
+      gap="sm"
+      wrap="nowrap"
+      align={align}
+      mih={ROW_MIN_HEIGHT}
+      opacity={disabled ? 0.5 : 1}
+      aria-disabled={disabled || undefined}
+      // Block clicks / focus through to children when disabled so a
+      // mutation-in-flight row can't fire a second mutation. The visual
+      // opacity above is intentionally kept so the row still reads as
+      // "soft" rather than removed entirely.
+      style={
+        disabled ? { pointerEvents: 'none', userSelect: 'none' } : undefined
+      }
+    >
+      <Group
+        gap="2xs"
+        wrap="nowrap"
+        align="center"
+        w={labelWidth}
+        miw={labelWidth}
+        mih={ROW_MIN_HEIGHT}
+        c="text.subdued.default"
+      >
+        {icon}
+        <Text variant="body1" c="text.subdued.default">
+          {label}
+        </Text>
+      </Group>
+      <Box flex={1} miw={0}>
+        {children}
+      </Box>
+    </Group>
+  );
+}

package/src/components/PropertyRow/index.ts

@@ -0,0 +1,2 @@
+export { PropertyRow } from './PropertyRow';
+export type { PropertyRowProps } from './PropertyRow';