vinta-schedule-design-system 0.1.0

package/src/layout/container.tsx

@@ -0,0 +1,39 @@
+import * as React from 'react';
+
+import { cn } from '../lib/utils';
+import { Box, type BoxProps } from './box';
+import type { Size } from './layout-style';
+
+/**
+ * Container — horizontal layout frame. Centers content and applies the design
+ * system's page margins (32px). `width` caps the content:
+ *   contained → 1200px (DS --container-max)   prose → 68ch   full → edge-to-edge
+ *
+ * Accepts all Box style props (e.g. `py`, `bg`) on top of the width cap.
+ */
+export interface ContainerProps extends Omit<BoxProps, 'width' | 'maxWidth'> {
+  width?: 'contained' | 'prose' | 'full';
+}
+
+const MAX_WIDTH: Record<NonNullable<ContainerProps['width']>, Size> = {
+  contained: 1200,
+  prose: '68ch',
+  full: 'none',
+};
+
+const Container = React.forwardRef<HTMLElement, ContainerProps>(
+  function Container({ className, width = 'contained', ...box }, ref) {
+    return (
+      <Box
+        ref={ref}
+        mx='auto'
+        width='full'
+        maxWidth={MAX_WIDTH[width]}
+        className={cn('px-4 md:px-8', className)}
+        {...box}
+      />
+    );
+  }
+);
+
+export { Container };

package/src/layout/divider.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import type { CSSProperties } from 'react';
+
+import { cn } from '../lib/utils';
+import {
+  color,
+  resolveSpace,
+  type ColorToken,
+  type Space,
+} from './layout-style';
+
+export interface DividerProps extends React.HTMLAttributes<HTMLDivElement> {
+  orientation?: 'horizontal' | 'vertical';
+  /** Line color token. Defaults to `border`. */
+  tone?: ColorToken;
+  /** Margin on the cross axis (space around the line). */
+  spacing?: Space;
+}
+
+/**
+ * Divider — a hairline rule between content. Horizontal by default; set
+ * `orientation="vertical"` inside an HStack.
+ */
+const Divider = React.forwardRef<HTMLDivElement, DividerProps>(function Divider(
+  {
+    className,
+    style,
+    orientation = 'horizontal',
+    tone = 'border',
+    spacing,
+    ...props
+  },
+  ref
+) {
+  const vertical = orientation === 'vertical';
+  const gap = spacing != null ? resolveSpace(spacing) : undefined;
+  const s: CSSProperties = vertical
+    ? {
+        width: '1px',
+        alignSelf: 'stretch',
+        backgroundColor: color(tone),
+        marginLeft: gap,
+        marginRight: gap,
+      }
+    : {
+        height: '1px',
+        width: '100%',
+        backgroundColor: color(tone),
+        marginTop: gap,
+        marginBottom: gap,
+      };
+  return (
+    <div
+      ref={ref}
+      role='separator'
+      aria-orientation={orientation}
+      className={cn(className)}
+      style={{ ...s, ...style }}
+      {...props}
+    />
+  );
+});
+
+export { Divider };

package/src/layout/flex.stories.tsx

@@ -0,0 +1,109 @@
+import type { Meta, StoryObj } from '../story-types';
+
+import { Flex, HStack, VStack } from './flex';
+import { Box } from './box';
+import { Spacer } from './spacer';
+import { Center } from './center';
+import { Divider } from './divider';
+import { Button } from '../ui/button';
+
+const meta = {
+  title: 'Layout/Flex',
+  component: Flex,
+  tags: ['autodocs'],
+  // FlexProps = flex vocabulary (direction/align/justify/wrap/gap) + the shared
+  // BoxStyleProps. A useful subset is curated; `children` is the composed
+  // content slot (§3) and `className`/`style` stay unexposed (§6).
+  argTypes: {
+    direction: {
+      control: 'inline-radio',
+      options: ['row', 'column', 'row-reverse', 'column-reverse'],
+    },
+    align: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'stretch', 'baseline'],
+    },
+    justify: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'between', 'around', 'evenly'],
+    },
+    gap: { control: 'select', options: [0, 2, 4, 6, 8] },
+    wrap: { control: 'boolean' },
+    inline: { control: 'boolean' },
+    p: { control: 'select', options: [0, 2, 4, 6, 8] },
+    bg: {
+      control: 'select',
+      options: ['background', 'card', 'muted', 'accent'],
+    },
+    radius: {
+      control: 'select',
+      options: ['none', 'sm', 'md', 'lg', 'xl', '2xl', 'full'],
+    },
+  },
+  args: { gap: 4, align: 'center', justify: 'start' },
+  parameters: { puck: { slots: ['children'] } },
+} satisfies Meta<typeof Flex>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const Item = ({ children }: { children: React.ReactNode }) => (
+  <Box bg='vinta-50' color='vinta-700' px={4} py={2} radius='md'>
+    {children}
+  </Box>
+);
+
+export const Playground: Story = {
+  render: (args) => (
+    <Flex {...args}>
+      <Item>One</Item>
+      <Item>Two</Item>
+      <Item>Three</Item>
+    </Flex>
+  ),
+};
+
+export const SpaceBetween: Story = {
+  name: 'HStack + Spacer (toolbar)',
+  render: () => (
+    <HStack gap={3} p={3} bg='card' radius='lg' border>
+      <Item>Logo</Item>
+      <Spacer />
+      <Button variant='ghost' size='sm'>
+        Settings
+      </Button>
+      <Button size='sm'>New</Button>
+    </HStack>
+  ),
+};
+
+export const Stacks: Story = {
+  render: () => (
+    <Flex gap={8} align='start'>
+      <VStack gap={2}>
+        <Item>VStack 1</Item>
+        <Item>VStack 2</Item>
+        <Item>VStack 3</Item>
+      </VStack>
+      <Divider orientation='vertical' />
+      <HStack gap={2}>
+        <Item>HStack 1</Item>
+        <Item>HStack 2</Item>
+      </HStack>
+    </Flex>
+  ),
+};
+
+export const CenterAndDivider: Story = {
+  render: () => (
+    <VStack gap={4}>
+      <Center bg='muted' radius='lg' height={120}>
+        <Item>Centered</Item>
+      </Center>
+      <Divider />
+      <Center bg='muted' radius='lg' height={80}>
+        <span className='text-muted-foreground text-sm'>Below the divider</span>
+      </Center>
+    </VStack>
+  ),
+};

package/src/layout/flex.test.tsx

@@ -0,0 +1,71 @@
+/**
+ * Flex / Grid gap regression tests.
+ *
+ * Guards the bug where the `gap` shorthand was emitted alongside `undefined`
+ * `rowGap`/`columnGap` longhands: React warns about mixing shorthand +
+ * longhand and DROPS the shorthand on rerender, silently zeroing the gap
+ * (which glued labels to switches/checkboxes/radios). The fix only assigns the
+ * gap keys that are actually set.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Flex, HStack } from './flex';
+import { Grid } from './grid';
+
+describe('Flex gap', () => {
+  it('emits the gap shorthand and NO rowGap/columnGap longhands when only gap is set', () => {
+    const { container } = render(
+      <HStack gap={2}>
+        <span>a</span>
+        <span>b</span>
+      </HStack>
+    );
+    const el = container.firstElementChild as HTMLElement;
+    expect(el.style.display).toBe('flex');
+    expect(el.style.gap).toBe('0.5rem');
+    // The longhands must be absent — their presence (even empty) is what made
+    // React drop the shorthand.
+    expect(el.style.rowGap).toBe('');
+    expect(el.style.columnGap).toBe('');
+  });
+
+  it('omits gap entirely when not provided', () => {
+    const { container } = render(
+      <Flex>
+        <span>a</span>
+      </Flex>
+    );
+    const el = container.firstElementChild as HTMLElement;
+    expect(el.style.gap).toBe('');
+    expect(el.style.rowGap).toBe('');
+    expect(el.style.columnGap).toBe('');
+  });
+
+  it('uses longhands (no shorthand) when only rowGap/columnGap are set', () => {
+    const { container } = render(
+      <Flex rowGap={2} columnGap={4}>
+        <span>a</span>
+      </Flex>
+    );
+    const el = container.firstElementChild as HTMLElement;
+    expect(el.style.rowGap).toBe('0.5rem');
+    expect(el.style.columnGap).toBe('1rem');
+    expect(el.style.gap).toBe('');
+  });
+});
+
+describe('Grid gap', () => {
+  it('emits the gap shorthand and NO longhands when only gap is set', () => {
+    const { container } = render(
+      <Grid gap={3}>
+        <span>a</span>
+      </Grid>
+    );
+    const el = container.firstElementChild as HTMLElement;
+    expect(el.style.display).toBe('grid');
+    expect(el.style.gap).toBe('0.75rem');
+    expect(el.style.rowGap).toBe('');
+    expect(el.style.columnGap).toBe('');
+  });
+});

package/src/layout/flex.tsx

@@ -0,0 +1,112 @@
+import * as React from 'react';
+import type { CSSProperties } from 'react';
+
+import { cn } from '../lib/utils';
+import {
+  boxStyle,
+  splitBoxProps,
+  resolveSpace,
+  type BoxStyleProps,
+  type Space,
+} from './layout-style';
+
+type Align = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+type Justify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+
+const ALIGN: Record<Align, CSSProperties['alignItems']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+  baseline: 'baseline',
+};
+
+const JUSTIFY: Record<Justify, CSSProperties['justifyContent']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+export interface FlexProps
+  extends BoxStyleProps, Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+  as?: React.ElementType;
+  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+  align?: Align;
+  justify?: Justify;
+  wrap?: boolean | 'reverse';
+  gap?: Space;
+  rowGap?: Space;
+  columnGap?: Space;
+  inline?: boolean;
+}
+
+/**
+ * Flex — flexbox container driven by props. Composes all Box style props plus
+ * direction / align / justify / wrap / gap.
+ *
+ *   <Flex justify="between" align="center" gap={4}>…</Flex>
+ */
+const Flex = React.forwardRef<HTMLElement, FlexProps>(function Flex(
+  {
+    as: Comp = 'div',
+    className,
+    style,
+    direction = 'row',
+    align,
+    justify,
+    wrap,
+    gap,
+    rowGap,
+    columnGap,
+    inline,
+    ...boxProps
+  },
+  ref
+) {
+  const { style: resolved, rest } = splitBoxProps(boxProps);
+  const flexStyle: CSSProperties = {
+    display: inline ? 'inline-flex' : 'flex',
+    flexDirection: direction,
+    alignItems: align ? ALIGN[align] : undefined,
+    justifyContent: justify ? JUSTIFY[justify] : undefined,
+    flexWrap:
+      wrap === true ? 'wrap' : wrap === 'reverse' ? 'wrap-reverse' : undefined,
+  };
+  // Only assign the gap keys that are actually set. Emitting the `gap`
+  // shorthand alongside `undefined` `rowGap`/`columnGap` longhands makes React
+  // warn about mixing shorthand + longhand and DROP the shorthand on rerender —
+  // which silently zeroed the gap (glued labels next to switches/checkboxes).
+  if (gap != null) flexStyle.gap = resolveSpace(gap);
+  if (rowGap != null) flexStyle.rowGap = resolveSpace(rowGap);
+  if (columnGap != null) flexStyle.columnGap = resolveSpace(columnGap);
+  return (
+    <Comp
+      ref={ref}
+      className={cn(className)}
+      style={{ ...resolved, ...flexStyle, ...style }}
+      {...rest}
+    />
+  );
+});
+
+export type StackProps = Omit<FlexProps, 'direction'>;
+
+/** Vertical flex stack. */
+const VStack = React.forwardRef<HTMLElement, StackProps>(
+  function VStack(props, ref) {
+    return <Flex ref={ref} direction='column' {...props} />;
+  }
+);
+
+/** Horizontal flex stack (centers items vertically by default). */
+const HStack = React.forwardRef<HTMLElement, StackProps>(function HStack(
+  { align = 'center', ...props },
+  ref
+) {
+  return <Flex ref={ref} direction='row' align={align} {...props} />;
+});
+
+export { Flex, HStack, VStack, boxStyle };

package/src/layout/grid.stories.tsx

@@ -0,0 +1,91 @@
+import type { Meta, StoryObj } from '../story-types';
+
+import { Grid, GridItem } from './grid';
+
+const meta = {
+  title: 'Layout/Grid',
+  component: Grid,
+  tags: ['autodocs'],
+  // GridProps = grid vocabulary (columns/rows/gap/align/justify/inline) + the
+  // shared BoxStyleProps. `children` is the composed content slot (§3).
+  argTypes: {
+    columns: { control: { type: 'number', min: 1, max: 12 } },
+    gap: { control: 'select', options: [0, 1, 2, 3, 4, 5, 6, 8] },
+    rowGap: { control: 'select', options: [0, 1, 2, 3, 4, 5, 6, 8] },
+    columnGap: { control: 'select', options: [0, 1, 2, 3, 4, 5, 6, 8] },
+    align: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'stretch'],
+    },
+    justify: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'stretch'],
+    },
+    p: { control: 'select', options: [0, 2, 4, 6, 8] },
+  },
+  args: { columns: 12, gap: 6 },
+  parameters: { puck: { slots: ['children'] } },
+} satisfies Meta<typeof Grid>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const Cell = ({ children }: { children: React.ReactNode }) => (
+  <div className='bg-vinta-50 text-vinta-700 rounded-md px-3 py-4 text-center font-mono text-xs'>
+    {children}
+  </div>
+);
+
+export const TwelveColumns: Story = {
+  args: { columns: 12, gap: 6 },
+  render: (args) => (
+    <Grid {...args}>
+      {Array.from({ length: 12 }).map((_, i) => (
+        <GridItem key={i} span={1}>
+          <Cell>{i + 1}</Cell>
+        </GridItem>
+      ))}
+    </Grid>
+  ),
+};
+
+export const Spans: Story = {
+  render: () => (
+    <Grid gap={4}>
+      <GridItem span={6}>
+        <Cell>span 6</Cell>
+      </GridItem>
+      <GridItem span={6}>
+        <Cell>span 6</Cell>
+      </GridItem>
+      <GridItem span={4}>
+        <Cell>span 4</Cell>
+      </GridItem>
+      <GridItem span={4}>
+        <Cell>span 4</Cell>
+      </GridItem>
+      <GridItem span={4}>
+        <Cell>span 4</Cell>
+      </GridItem>
+      <GridItem span={8}>
+        <Cell>span 8</Cell>
+      </GridItem>
+      <GridItem span={4}>
+        <Cell>span 4</Cell>
+      </GridItem>
+    </Grid>
+  ),
+};
+
+export const EqualColumns: Story = {
+  name: 'Equal columns (columns=3)',
+  render: () => (
+    <Grid columns={3} gap={4}>
+      {Array.from({ length: 6 }).map((_, i) => (
+        <GridItem key={i}>
+          <Cell>{i + 1}</Cell>
+        </GridItem>
+      ))}
+    </Grid>
+  ),
+};

package/src/layout/grid.tsx

@@ -0,0 +1,132 @@
+import * as React from 'react';
+import type { CSSProperties } from 'react';
+
+import { cn } from '../lib/utils';
+import {
+  splitBoxProps,
+  resolveSpace,
+  type BoxStyleProps,
+  type Space,
+} from './layout-style';
+
+type Align = 'start' | 'center' | 'end' | 'stretch';
+type Justify = 'start' | 'center' | 'end' | 'stretch';
+
+const ALIGN: Record<Align, CSSProperties['alignItems']> = {
+  start: 'start',
+  center: 'center',
+  end: 'end',
+  stretch: 'stretch',
+};
+
+export interface GridProps
+  extends BoxStyleProps, Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+  as?: React.ElementType;
+  /** Number of equal columns, or a raw grid-template-columns string. */
+  columns?: number | string;
+  rows?: number | string;
+  gap?: Space;
+  rowGap?: Space;
+  columnGap?: Space;
+  align?: Align;
+  justify?: Justify;
+  inline?: boolean;
+}
+
+function template(value: number | string | undefined): string | undefined {
+  if (value == null) return undefined;
+  if (typeof value === 'number') return `repeat(${value}, minmax(0, 1fr))`;
+  return value;
+}
+
+/**
+ * Grid — CSS grid container. Defaults to the design system's 12-column grid;
+ * pass `columns` for any count (or a template string). Compose with <GridItem>.
+ *
+ *   <Grid columns={3} gap={4}>…</Grid>
+ */
+const Grid = React.forwardRef<HTMLElement, GridProps>(function Grid(
+  {
+    as: Comp = 'div',
+    className,
+    style,
+    columns = 12,
+    rows,
+    gap = 6,
+    rowGap,
+    columnGap,
+    align,
+    justify,
+    inline,
+    ...boxProps
+  },
+  ref
+) {
+  const { style: resolved, rest } = splitBoxProps(boxProps);
+  const gridStyle: CSSProperties = {
+    display: inline ? 'inline-grid' : 'grid',
+    gridTemplateColumns: template(columns),
+    gridTemplateRows: template(rows),
+    alignItems: align ? ALIGN[align] : undefined,
+    justifyItems: justify ? ALIGN[justify] : undefined,
+  };
+  // Never emit the `gap` shorthand together with `undefined` `rowGap`/`columnGap`
+  // longhands — React drops the shorthand on rerender, zeroing the gap.
+  if (gap != null) gridStyle.gap = resolveSpace(gap);
+  if (rowGap != null) gridStyle.rowGap = resolveSpace(rowGap);
+  if (columnGap != null) gridStyle.columnGap = resolveSpace(columnGap);
+  return (
+    <Comp
+      ref={ref}
+      className={cn(className)}
+      style={{ ...resolved, ...gridStyle, ...style }}
+      {...rest}
+    />
+  );
+});
+
+export interface GridItemProps
+  extends BoxStyleProps, Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+  as?: React.ElementType;
+  /** Columns to span. */
+  span?: number;
+  /** Rows to span. */
+  rowSpan?: number;
+  colStart?: number;
+  colEnd?: number;
+}
+
+const GridItem = React.forwardRef<HTMLElement, GridItemProps>(function GridItem(
+  {
+    as: Comp = 'div',
+    className,
+    style,
+    span,
+    rowSpan,
+    colStart,
+    colEnd,
+    ...boxProps
+  },
+  ref
+) {
+  const { style: resolved, rest } = splitBoxProps(boxProps);
+  const itemStyle: CSSProperties = {
+    gridColumn:
+      colStart != null || colEnd != null
+        ? `${colStart ?? 'auto'} / ${colEnd ?? (span != null ? `span ${span}` : 'auto')}`
+        : span != null
+          ? `span ${span} / span ${span}`
+          : undefined,
+    gridRow: rowSpan != null ? `span ${rowSpan} / span ${rowSpan}` : undefined,
+  };
+  return (
+    <Comp
+      ref={ref}
+      className={cn(className)}
+      style={{ ...resolved, ...itemStyle, ...style }}
+      {...rest}
+    />
+  );
+});
+
+export { Grid, GridItem };

package/src/layout/heading.tsx

@@ -0,0 +1,53 @@
+import * as React from 'react';
+
+import { Text, type TextProps, type TextSize, type TextWeight } from './text';
+
+type Level = 1 | 2 | 3 | 4 | 5 | 6;
+
+const DEFAULT_SIZE: Record<Level, TextSize> = {
+  1: '5xl',
+  2: '4xl',
+  3: '2xl',
+  4: 'xl',
+  5: 'lg',
+  6: 'base',
+};
+
+const DEFAULT_WEIGHT: Record<Level, TextWeight> = {
+  1: 'bold',
+  2: 'semibold',
+  3: 'semibold',
+  4: 'semibold',
+  5: 'semibold',
+  6: 'semibold',
+};
+
+export interface HeadingProps extends TextProps {
+  /** Heading level 1–6. Sets the tag and default size/weight. */
+  level?: Level;
+}
+
+/**
+ * Heading — semantic heading with design-system defaults per level. Override
+ * any token via props.
+ *
+ *   <Heading level={2}>Section title</Heading>
+ */
+const Heading = React.forwardRef<HTMLElement, HeadingProps>(function Heading(
+  { level = 2, size, weight, tracking = 'tight', leading = 'tight', ...props },
+  ref
+) {
+  return (
+    <Text
+      ref={ref}
+      as={`h${level}`}
+      size={size ?? DEFAULT_SIZE[level]}
+      weight={weight ?? DEFAULT_WEIGHT[level]}
+      tracking={tracking}
+      leading={leading}
+      {...props}
+    />
+  );
+});
+
+export { Heading };