@scalepad/ui 0.1.0

package/src/components/DesignSystemPrimitives/LayoutPrimitives.tsx

@@ -0,0 +1,220 @@
+/**
+ * Design System Layout Primitives
+ *
+ * Wrapped versions of Mantine layout components with type-safe color props.
+ * These replace the direct Mantine re-exports to enforce design system tokens.
+ */
+
+import { Children, Fragment, type ReactElement } from 'react';
+
+import {
+  Box as MantineBox,
+  Center as MantineCenter,
+  factory,
+  type Factory,
+  Flex as MantineFlex,
+  Grid as MantineGrid,
+  Group as MantineGroup,
+  polymorphicFactory,
+  type PolymorphicFactory,
+  SimpleGrid as MantineSimpleGrid,
+  Stack as MantineStack,
+  type BoxProps as MantineBoxProps,
+  type CenterProps as MantineCenterProps,
+  type FlexProps as MantineFlexProps,
+  type GridCssVariables as MantineGridCssVariables,
+  type GridProps as MantineGridProps,
+  type GridStylesNames as MantineGridStylesNames,
+  type GroupProps as MantineGroupProps,
+  type SimpleGridProps as MantineSimpleGridProps,
+  type StackProps as MantineStackProps,
+} from '@mantine/core';
+
+import { Divider } from './InteractivePrimitives';
+import { resolveColorToken } from '../../utils/color-props';
+import {
+  createDesignComponent,
+  type WithDesignColors,
+} from '../../utils/createDesignComponent';
+import { withStaticComponents } from '../../utils/withStaticComponents';
+
+import type { StrokeColor } from '../../tokens/color-types';
+
+// Layout primitives - all use the standard DesignSystemColorProps (c, bg, borderColor)
+export const Box = createDesignComponent<
+  MantineBoxProps,
+  'div',
+  HTMLDivElement
+>(MantineBox, 'Box');
+export const Flex = createDesignComponent<
+  MantineFlexProps,
+  'div',
+  HTMLDivElement
+>(MantineFlex, 'Flex');
+
+export type StackProps = WithDesignColors<MantineStackProps> & {
+  /**
+   * Render a divider line between direct children (skipped after the last)
+   * so a list of items reads as separated rows without each child having to
+   * know its own position. Pass `true` for the default subtle stroke or a
+   * `StrokeColor` token to customize the colour.
+   *
+   * Implemented by interleaving Mantine `<Divider />` elements between
+   * children so the Stack's `gap` applies symmetrically on both sides — the
+   * line lands in the middle of the gutter rather than flush against one row.
+   *
+   * The interleaved nodes are plain `<div role="separator">` elements, which
+   * is fine for the default `<div>` Stack and any flex container that
+   * accepts arbitrary children. If you set `component` to a semantic list
+   * container (`ul`, `ol`, `dl`, `menu`) we leave the divider off — non-list
+   * children inside those wrappers are invalid HTML. A dev-mode warning is
+   * emitted so the misuse is caught at the call site.
+   */
+  divider?: boolean | StrokeColor;
+};
+
+// Stacks rendered as semantic list containers reject the divider prop — see
+// the `divider` JSDoc above for why.
+const LIST_LIKE_COMPONENTS = new Set(['ul', 'ol', 'dl', 'menu']);
+
+function isListLikeComponent(component: unknown): boolean {
+  return typeof component === 'string' && LIST_LIKE_COMPONENTS.has(component);
+}
+
+type StackFactory = PolymorphicFactory<{
+  props: StackProps;
+  defaultComponent: 'div';
+  defaultRef: HTMLDivElement;
+}>;
+
+export const Stack = polymorphicFactory<StackFactory>(
+  ({ c, bg, borderColor, divider, children, ref, ...rest }) => {
+    const resolvedProps: Record<string, unknown> = { ...rest, ref };
+
+    const resolvedC = resolveColorToken(c);
+    if (resolvedC !== undefined) {
+      resolvedProps.c = resolvedC;
+    }
+
+    const resolvedBg = resolveColorToken(bg);
+    if (resolvedBg !== undefined) {
+      resolvedProps.bg = resolvedBg;
+    }
+
+    if (borderColor) {
+      const resolvedBorderColor = resolveColorToken(borderColor);
+      resolvedProps.bd = `1px solid ${resolvedBorderColor}`;
+    }
+
+    const stackComponent = (rest as { component?: unknown }).component;
+
+    if (!divider) {
+      return <MantineStack {...resolvedProps}>{children}</MantineStack>;
+    }
+
+    if (isListLikeComponent(stackComponent)) {
+      if (process.env.NODE_ENV !== 'production') {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `<Stack divider> ignored: cannot interleave <Divider /> between <li> children inside <${String(
+            stackComponent,
+          )}>. Render the list manually or wrap each item in its own bordered row.`,
+        );
+      }
+      return <MantineStack {...resolvedProps}>{children}</MantineStack>;
+    }
+
+    const dividerColor: StrokeColor =
+      divider === true ? 'stroke.subdued.default' : divider;
+
+    // `Children.toArray` filters out null/false/undefined and assigns stable
+    // keys, so conditional children don't end up with extra dividers around
+    // empty slots.
+    const items = Children.toArray(children);
+
+    return (
+      <MantineStack {...resolvedProps}>
+        {items.map((child, idx) => {
+          const childKey =
+            (child as ReactElement).key != null
+              ? (child as ReactElement).key
+              : `stack-item-${idx}`;
+          return (
+            <Fragment key={childKey}>
+              {child}
+              {idx < items.length - 1 ? <Divider color={dividerColor} /> : null}
+            </Fragment>
+          );
+        })}
+      </MantineStack>
+    );
+  },
+);
+Stack.displayName = 'Stack';
+export const Group = createDesignComponent<
+  MantineGroupProps,
+  'div',
+  HTMLDivElement
+>(MantineGroup, 'Group');
+export const SimpleGrid = createDesignComponent<
+  MantineSimpleGridProps,
+  'div',
+  HTMLDivElement
+>(MantineSimpleGrid, 'SimpleGrid');
+export const Center = createDesignComponent<
+  MantineCenterProps,
+  'div',
+  HTMLDivElement
+>(MantineCenter, 'Center');
+
+// Grid needs special handling to preserve Grid.Col compound component
+export type GridProps = WithDesignColors<MantineGridProps> & {
+  gap?: MantineGridProps['gap'];
+  rowGap?: MantineGridProps['rowGap'];
+  columnGap?: MantineGridProps['columnGap'];
+};
+
+type DesignGridFactory = Factory<{
+  props: GridProps;
+  ref: HTMLDivElement;
+  stylesNames: MantineGridStylesNames;
+  vars: MantineGridCssVariables;
+  staticComponents: {
+    Col: typeof MantineGrid.Col;
+  };
+}>;
+
+const GridRoot = factory<DesignGridFactory>(
+  ({ c, bg, borderColor, ref, ...rest }) => {
+    const resolvedProps: Record<string, unknown> = { ...rest, ref };
+
+    const resolvedC = resolveColorToken(c);
+    if (resolvedC !== undefined) {
+      resolvedProps.c = resolvedC;
+    }
+
+    const resolvedBg = resolveColorToken(bg);
+    if (resolvedBg !== undefined) {
+      resolvedProps.bg = resolvedBg;
+    }
+
+    if (borderColor) {
+      const resolvedBorderColor = resolveColorToken(borderColor);
+      resolvedProps.bd = `1px solid ${resolvedBorderColor}`;
+    }
+
+    return <MantineGrid {...resolvedProps} />;
+  },
+);
+
+GridRoot.displayName = 'Grid';
+
+export const Grid = withStaticComponents(GridRoot, { Col: MantineGrid.Col });
+
+// Export prop types for consumers (StackProps is exported above with the
+// `divider` prop so its definition stays next to the wrapped Stack component).
+export type BoxProps = WithDesignColors<MantineBoxProps>;
+export type FlexProps = WithDesignColors<MantineFlexProps>;
+export type GroupProps = WithDesignColors<MantineGroupProps>;
+export type SimpleGridProps = WithDesignColors<MantineSimpleGridProps>;
+export type CenterProps = WithDesignColors<MantineCenterProps>;

package/src/components/DesignSystemPrimitives/LayoutPrimitives.types.tsx

@@ -0,0 +1,15 @@
+import { Grid, Group, SimpleGrid, Stack } from './LayoutPrimitives';
+
+void (
+  <>
+    <Grid gap="sm" rowGap="xs" columnGap="md" grow>
+      <Grid.Col span="content">Column</Grid.Col>
+    </Grid>
+    <Group gap="sm">Grouped content</Group>
+    <Stack gap="md">Stacked content</Stack>
+    <SimpleGrid spacing="sm" verticalSpacing="lg" cols={2}>
+      <div>One</div>
+      <div>Two</div>
+    </SimpleGrid>
+  </>
+);

package/src/components/DesignSystemPrimitives/SurfacePrimitives.tsx

@@ -0,0 +1,46 @@
+/**
+ * Design System Surface Primitives
+ *
+ * Wrapped versions of Mantine surface/container components with type-safe color props.
+ */
+
+import {
+  Card as MantineCard,
+  Container as MantineContainer,
+  Paper as MantinePaper,
+  type CardProps as MantineCardProps,
+  type ContainerProps as MantineContainerProps,
+  type PaperProps as MantinePaperProps,
+} from '@mantine/core';
+
+import {
+  createDesignComponent,
+  type WithDesignColors,
+} from '../../utils/createDesignComponent';
+import { withStaticComponents } from '../../utils/withStaticComponents';
+
+// Surface primitives
+export const Paper = createDesignComponent<
+  MantinePaperProps,
+  'div',
+  HTMLDivElement
+>(MantinePaper, 'Paper');
+export const Container = createDesignComponent<
+  MantineContainerProps,
+  'div',
+  HTMLDivElement
+>(MantineContainer, 'Container');
+
+// Card needs special handling to preserve Card.Section compound component
+const CardBase = createDesignComponent<MantineCardProps, 'div', HTMLDivElement>(
+  MantineCard,
+  'Card',
+);
+export const Card = withStaticComponents(CardBase, {
+  Section: MantineCard.Section,
+});
+
+// Export prop types for consumers
+export type CardProps = WithDesignColors<MantineCardProps>;
+export type PaperProps = WithDesignColors<MantinePaperProps>;
+export type ContainerProps = WithDesignColors<MantineContainerProps>;

package/src/components/DesignSystemPrimitives/index.ts

@@ -0,0 +1,55 @@
+import { Menu } from '../Menu';
+
+// Design System Primitives - wrapped Mantine components with typed color props
+
+// Layout primitives
+export { FluidGrid } from './FluidGrid';
+export type { FluidGridProps } from './FluidGrid';
+export {
+  Box,
+  Center,
+  Flex,
+  Grid,
+  Group,
+  SimpleGrid,
+  Stack,
+} from './LayoutPrimitives';
+export type {
+  BoxProps,
+  CenterProps,
+  FlexProps,
+  GridProps,
+  GroupProps,
+  SimpleGridProps,
+  StackProps,
+} from './LayoutPrimitives';
+
+// Surface primitives
+export { Card, Container, Paper } from './SurfacePrimitives';
+export type {
+  CardProps,
+  ContainerProps,
+  PaperProps,
+} from './SurfacePrimitives';
+export { Menu };
+
+export const MenuItem: typeof Menu.Item = Menu.Item;
+export type { MenuItemProps, MenuItemVariant, MenuProps } from '../Menu';
+
+// Interactive primitives
+export {
+  Alert,
+  Avatar,
+  Divider,
+  Loader,
+  NavLink,
+  Switch,
+} from './InteractivePrimitives';
+export type {
+  AlertProps,
+  AvatarProps,
+  DividerProps,
+  LoaderProps,
+  NavLinkProps,
+  SwitchProps,
+} from './InteractivePrimitives';

package/src/components/Details/Details.css.ts

@@ -0,0 +1,74 @@
+/**
+ * Details / Summary component styles – vanilla-extract with semantic design tokens
+ */
+
+import { style } from '@vanilla-extract/css';
+
+import { mantineVars } from '../../theme/mantineVars';
+import { tokens } from '../../theme/themeContract.css';
+
+export const details = style({
+  overflow: 'hidden',
+  width: '100%',
+  border: `1px solid ${tokens.color.stroke.subduedDefault}`,
+  borderRadius: tokens.radius.lg,
+  selectors: {
+    [`${mantineVars.darkSelector} &`]: {
+      backgroundColor: tokens.color.background.default,
+      borderColor: tokens.color.stroke.default,
+    },
+  },
+});
+
+export const summary = style({
+  cursor: 'pointer',
+  listStyle: 'none',
+  minHeight: 0,
+  selectors: {
+    '&:focus-visible': {
+      outline: `2px solid ${tokens.color.stroke.primaryDefault}`,
+      outlineOffset: '4px',
+      borderRadius: tokens.radius.sm,
+    },
+  },
+});
+
+export const chevronWrapper = style({
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  flexShrink: 0,
+  minWidth: 34,
+  minHeight: 34,
+  color: tokens.color.text.subduedDefault,
+});
+
+export const chevronIcon = style({
+  flexShrink: 0,
+  transition: 'transform 0.2s ease',
+  selectors: {
+    [`${details}[open] &`]: {
+      transform: 'rotate(90deg)',
+    },
+  },
+});
+
+export const summaryContent = style({
+  flex: 1,
+  minWidth: 0,
+});
+
+export const actions = style({
+  flexShrink: 0,
+});
+
+export const contentWrapper = style({
+  borderTop: `1px solid ${tokens.color.stroke.default}`,
+  selectors: {
+    [`${mantineVars.darkSelector} &`]: {
+      borderTopColor: tokens.color.stroke.default,
+    },
+  },
+});
+
+export const content = style({});

package/src/components/Details/Details.tsx

@@ -0,0 +1,140 @@
+import { useState, type CSSProperties, type ReactNode } from 'react';
+
+import { ChevronRight } from 'lucide-react';
+
+import { Box, Flex, type BoxProps } from '../DesignSystemPrimitives';
+import * as classes from './Details.css';
+
+export interface DetailsProps {
+  /** Content of the summary row (title, subtitle, etc.) */
+  summary: ReactNode;
+  /** Expandable content shown when open */
+  children: ReactNode;
+  /** Optional action icons rendered on the far right of the summary row */
+  actions?: ReactNode;
+  /** Whether the details start expanded (uncontrolled) */
+  defaultOpen?: boolean;
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback when open state changes (use with controlled `open`) */
+  onOpenChange?: (open: boolean) => void;
+  /** Optional background color using the same Mantine-style prop shape as layout primitives */
+  bg?: BoxProps['bg'];
+  /** Optional border override using Mantine's `bd` prop format */
+  bd?: BoxProps['bd'];
+  /** Optional border radius override using Mantine's `bdrs` prop format */
+  bdrs?: BoxProps['bdrs'];
+  /** Optional padding override using Mantine's `p` prop format */
+  p?: BoxProps['p'];
+  /** Hide the built-in chevron when the summary provides its own icon */
+  hideChevron?: boolean;
+}
+
+/**
+ * Disclosure widget using native <details> and <summary> per W3C spec.
+ * Summary row shows a chevron (right when closed, down when open), summary content,
+ * and optional actions on the far right. When expanded, a divider and content
+ * area are shown; the border encloses the full block.
+ *
+ * @example
+ * ```tsx
+ * <Details
+ *   summary={<><Text variant="body1.stronger">Sales Department</Text><Text variant="caption1" c="text.subdued.default">21 Members</Text></>}
+ *   actions={<IconButton variant="ghost" size="sm" aria-label="More"><MoreVertical /></IconButton>}
+ * >
+ *   <Stack gap="md">...</Stack>
+ * </Details>
+ * ```
+ */
+export function Details({
+  summary,
+  children,
+  actions,
+  defaultOpen,
+  open: controlledOpen,
+  onOpenChange,
+  bg,
+  p = 'md',
+  bd,
+  bdrs,
+  hideChevron = false,
+}: DetailsProps) {
+  const isControlled = controlledOpen !== undefined;
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(
+    defaultOpen ?? false,
+  );
+
+  const handleToggle = (e: React.ToggleEvent<HTMLDetailsElement>) => {
+    const nextOpen = e.currentTarget.open;
+
+    if (isControlled) {
+      e.preventDefault();
+      onOpenChange?.(!controlledOpen);
+      return;
+    }
+
+    setUncontrolledOpen(nextOpen);
+    onOpenChange?.(nextOpen);
+  };
+
+  const contentWrapperStyle: CSSProperties | undefined =
+    typeof bd === 'string' || typeof bd === 'number'
+      ? { borderTop: bd }
+      : undefined;
+
+  return (
+    <Box
+      component="details"
+      className={classes.details}
+      open={isControlled ? controlledOpen : uncontrolledOpen}
+      onToggle={handleToggle}
+      bg={bg}
+      bd={bd}
+      bdrs={bdrs}
+      w="100%"
+    >
+      <Flex
+        component="summary"
+        align="center"
+        gap="xs"
+        p="xs"
+        className={classes.summary}
+      >
+        {!hideChevron ? (
+          <Flex
+            component="span"
+            align="center"
+            justify="center"
+            className={classes.chevronWrapper}
+            aria-hidden
+            data-testid="details-chevron"
+          >
+            <ChevronRight size={16} className={classes.chevronIcon} />
+          </Flex>
+        ) : null}
+        <Box component="span" className={classes.summaryContent}>
+          {summary}
+        </Box>
+        {actions != null ? (
+          <Flex
+            component="span"
+            align="center"
+            gap="xs"
+            className={classes.actions}
+          >
+            {actions}
+          </Flex>
+        ) : null}
+      </Flex>
+      <Box
+        component="div"
+        className={classes.contentWrapper}
+        style={contentWrapperStyle}
+      >
+        <Box component="div" p={p} className={classes.content}>
+          {children}
+        </Box>
+      </Box>
+    </Box>
+  );
+}

package/src/components/Details/index.ts

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

package/src/components/DownloadCard/DownloadCard.css.ts

@@ -0,0 +1,22 @@
+/**
+ * DownloadCard component styles – vanilla-extract with semantic design tokens
+ */
+
+import { style } from '@vanilla-extract/css';
+
+import { mantineVars } from '../../theme/mantineVars';
+import { tokens } from '../../theme/themeContract.css';
+
+export const container = style({
+  backgroundColor: tokens.color.background.default,
+  border: `1px solid ${tokens.color.stroke.default}`,
+  borderRadius: tokens.radius.lg,
+  padding: `${tokens.spacing.xs} ${tokens.spacing.md}`,
+  width: '100%',
+  selectors: {
+    [`${mantineVars.darkSelector} &`]: {
+      backgroundColor: tokens.color.background.default,
+      borderColor: tokens.color.stroke.default,
+    },
+  },
+});

package/src/components/DownloadCard/DownloadCard.tsx

@@ -0,0 +1,63 @@
+import { Download } from 'lucide-react';
+
+import { Box, Flex } from '@mantine/core';
+
+import { IconButton } from '../IconButton';
+import { Text } from '../Typography';
+import * as classes from './DownloadCard.css';
+
+export interface DownloadCardProps {
+  /** Platform name (e.g., "Windows", "MacOS") */
+  platform: string;
+  /** Version information (e.g., "Latest (1.4.2)") */
+  version: string;
+  /** Callback when download button is clicked */
+  onDownload?: () => void;
+}
+
+/**
+ * DownloadCard component for displaying downloadable installers.
+ *
+ * Features:
+ * - Platform name with medium font weight
+ * - Version information with muted color
+ * - Download icon button
+ * - White background with border
+ * - Horizontal layout with space-between
+ *
+ * @example
+ * ```tsx
+ * <DownloadCard
+ *   platform="Windows"
+ *   version="Latest (1.4.2)"
+ *   onDownload={() => console.log('Download Windows installer')}
+ * />
+ * ```
+ */
+export function DownloadCard({
+  platform,
+  version,
+  onDownload,
+}: DownloadCardProps) {
+  return (
+    <Box className={classes.container}>
+      <Flex justify="space-between" align="center" w="100%">
+        <Flex direction="column" gap="3xs">
+          <Text variant="body1.strong">{platform}</Text>
+          <Text variant="caption1" c="text.subdued.default">
+            {version}
+          </Text>
+        </Flex>
+
+        <IconButton
+          variant="outline"
+          size="md"
+          onClick={onDownload}
+          aria-label={`Download ${platform}`}
+        >
+          <Download size={16} />
+        </IconButton>
+      </Flex>
+    </Box>
+  );
+}

package/src/components/DownloadCard/index.ts

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

package/src/components/Drawer/Drawer.css.ts

@@ -0,0 +1,32 @@
+/**
+ * Drawer component styles – vanilla-extract
+ */
+
+import { style } from '@vanilla-extract/css';
+
+import { tokens } from '../../theme/themeContract.css';
+import { zIndex } from '../../tokens';
+
+export const resizeHandle = style({
+  position: 'absolute',
+  left: -5,
+  top: 0,
+  bottom: 0,
+  width: 10,
+  zIndex: zIndex.resizeHandle,
+  background: 'transparent',
+  cursor: 'ew-resize',
+  transition: 'background 0.2s',
+});
+
+export const resizing = style({
+  cursor: 'col-resize',
+});
+
+export const stickyHeader = style({
+  position: 'sticky',
+  top: `calc(${tokens.spacing.lg} * -1)`,
+  marginTop: `calc(${tokens.spacing.lg} * -1)`,
+  zIndex: zIndex.app,
+  backgroundColor: tokens.color.background.default,
+});