vinta-schedule-design-system 0.1.0

package/src/layout/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Layout kit — compose UIs from props, not classes.
+ *
+ * Primitives:   Box · Flex · HStack · VStack · Stack · Grid · GridItem ·
+ *               Center · Spacer · Section · Divider · Container
+ * Typography:   Text · Heading
+ * Composition:  Navbar · AppTopbar · PageHeader
+ * Shells:       AppShell · AuthLayout
+ */
+
+// Primitives
+export { Box, type BoxProps } from './box';
+export { Flex, HStack, VStack, type FlexProps, type StackProps } from './flex';
+export { Stack } from './stack';
+export { Grid, GridItem, type GridProps, type GridItemProps } from './grid';
+export { Center } from './center';
+export { Spacer } from './spacer';
+export { Section, type SectionProps } from './section';
+export { Divider, type DividerProps } from './divider';
+export { Container, type ContainerProps } from './container';
+
+// Typography
+export {
+  Text,
+  type TextProps,
+  type TextSize,
+  type TextWeight,
+  type TextFamily,
+} from './text';
+export { Heading, type HeadingProps } from './heading';
+
+// Style-prop vocabulary
+export type {
+  Space,
+  Radius,
+  Shadow,
+  ColorToken,
+  Size,
+  BoxStyleProps,
+} from './layout-style';
+
+// Composition + shells
+export { Navbar, BrandMark, type NavbarProps } from './navbar';
+export { AppTopbar, type AppTopbarProps } from './app-topbar';
+export { PageHeader, type PageHeaderProps } from './page-header';
+export { AppShell, type AppShellProps } from './app-shell';
+export { AuthLayout, type AuthLayoutProps } from './auth-layout';

package/src/layout/layout-style.ts

@@ -0,0 +1,291 @@
+import type { CSSProperties } from 'react';
+
+/**
+ * Shared style-prop vocabulary for the layout primitives. Values resolve to the
+ * design-system tokens (spacing scale, radius, shadow, color CSS vars) so the
+ * primitives can be composed purely through props — no Tailwind classes needed.
+ */
+
+/* 4px spacing scale (matches the DS --space-* tokens). */
+export type Space = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | 24;
+
+const SPACE_REM: Record<Space, string> = {
+  0: '0',
+  1: '0.25rem',
+  2: '0.5rem',
+  3: '0.75rem',
+  4: '1rem',
+  5: '1.25rem',
+  6: '1.5rem',
+  8: '2rem',
+  10: '2.5rem',
+  12: '3rem',
+  16: '4rem',
+  20: '5rem',
+  24: '6rem',
+};
+
+export type Radius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+
+const RADIUS: Record<Radius, string> = {
+  none: '0',
+  sm: 'var(--radius-sm)',
+  md: 'var(--radius-md)',
+  lg: 'var(--radius-lg)',
+  xl: 'var(--radius-xl)',
+  '2xl': 'var(--radius-2xl)',
+  full: '9999px',
+};
+
+export type Shadow = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+const SHADOW: Record<Shadow, string> = {
+  none: 'none',
+  xs: 'var(--shadow-xs)',
+  sm: 'var(--shadow-sm)',
+  md: 'var(--shadow-md)',
+  lg: 'var(--shadow-lg)',
+  xl: 'var(--shadow-xl)',
+};
+
+/**
+ * A design-token color name (e.g. 'primary', 'muted-foreground', 'vinta-600',
+ * 'border'). Resolves to `var(--<name>)`. Any raw CSS color string also works.
+ */
+export type ColorToken =
+  | 'background'
+  | 'foreground'
+  | 'card'
+  | 'card-foreground'
+  | 'popover'
+  | 'popover-foreground'
+  | 'primary'
+  | 'primary-foreground'
+  | 'secondary'
+  | 'secondary-foreground'
+  | 'muted'
+  | 'muted-foreground'
+  | 'accent'
+  | 'accent-foreground'
+  | 'destructive'
+  | 'destructive-foreground'
+  | 'success'
+  | 'warning'
+  | 'border'
+  | 'input'
+  | 'ring'
+  | `vinta-${50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950}`
+  | `teal-${100 | 300 | 500 | 600 | 700}`
+  | (string & {});
+
+export type Size = number | string;
+
+function size(v: Size | undefined): string | undefined {
+  if (v == null) return undefined;
+  if (typeof v === 'number') return `${v}px`;
+  if (v === 'full') return '100%';
+  if (v === 'screen') return '100vw';
+  if (v === 'min') return 'min-content';
+  if (v === 'max') return 'max-content';
+  if (v === 'fit') return 'fit-content';
+  return v;
+}
+
+function heightSize(v: Size | undefined): string | undefined {
+  if (v === 'screen') return '100vh';
+  return size(v);
+}
+
+function spacing(v: Space | 'auto' | undefined): string | undefined {
+  if (v == null) return undefined;
+  if (v === 'auto') return 'auto';
+  return SPACE_REM[v];
+}
+
+export function color(c: ColorToken | undefined): string | undefined {
+  if (c == null) return undefined;
+  // Raw CSS values (hex, rgb, var(), currentColor, transparent) pass through.
+  if (
+    c.startsWith('#') ||
+    c.startsWith('var(') ||
+    c.startsWith('rgb') ||
+    c.startsWith('hsl') ||
+    c.startsWith('oklch') ||
+    c === 'transparent' ||
+    c === 'currentColor' ||
+    c === 'inherit'
+  ) {
+    return c;
+  }
+  return `var(--${c})`;
+}
+
+/** Box style props supported by every primitive. */
+export interface BoxStyleProps {
+  // padding
+  p?: Space;
+  px?: Space;
+  py?: Space;
+  pt?: Space;
+  pr?: Space;
+  pb?: Space;
+  pl?: Space;
+  // margin
+  m?: Space | 'auto';
+  mx?: Space | 'auto';
+  my?: Space | 'auto';
+  mt?: Space | 'auto';
+  mr?: Space | 'auto';
+  mb?: Space | 'auto';
+  ml?: Space | 'auto';
+  // color / surface
+  bg?: ColorToken;
+  color?: ColorToken;
+  radius?: Radius;
+  shadow?: Shadow;
+  border?: boolean | number;
+  borderColor?: ColorToken;
+  // sizing
+  width?: Size;
+  height?: Size;
+  minWidth?: Size;
+  maxWidth?: Size;
+  minHeight?: Size;
+  maxHeight?: Size;
+  // box behavior
+  display?: CSSProperties['display'];
+  overflow?: CSSProperties['overflow'];
+  position?: CSSProperties['position'];
+  // flex item
+  grow?: boolean | number;
+  shrink?: boolean | number;
+  basis?: Size;
+  alignSelf?: CSSProperties['alignSelf'];
+  // escape hatch
+  textAlign?: CSSProperties['textAlign'];
+}
+
+const BOX_KEYS: (keyof BoxStyleProps)[] = [
+  'p',
+  'px',
+  'py',
+  'pt',
+  'pr',
+  'pb',
+  'pl',
+  'm',
+  'mx',
+  'my',
+  'mt',
+  'mr',
+  'mb',
+  'ml',
+  'bg',
+  'color',
+  'radius',
+  'shadow',
+  'border',
+  'borderColor',
+  'width',
+  'height',
+  'minWidth',
+  'maxWidth',
+  'minHeight',
+  'maxHeight',
+  'display',
+  'overflow',
+  'position',
+  'grow',
+  'shrink',
+  'basis',
+  'alignSelf',
+  'textAlign',
+];
+
+function flexNum(v: boolean | number | undefined): number | undefined {
+  if (v == null) return undefined;
+  return v === true ? 1 : v === false ? 0 : v;
+}
+
+/** Build a CSSProperties object from box style props. */
+export function boxStyle(props: BoxStyleProps): CSSProperties {
+  const s: CSSProperties = {};
+
+  // padding
+  if (props.p != null) s.padding = spacing(props.p);
+  if (props.px != null) {
+    s.paddingLeft = spacing(props.px);
+    s.paddingRight = spacing(props.px);
+  }
+  if (props.py != null) {
+    s.paddingTop = spacing(props.py);
+    s.paddingBottom = spacing(props.py);
+  }
+  if (props.pt != null) s.paddingTop = spacing(props.pt);
+  if (props.pr != null) s.paddingRight = spacing(props.pr);
+  if (props.pb != null) s.paddingBottom = spacing(props.pb);
+  if (props.pl != null) s.paddingLeft = spacing(props.pl);
+
+  // margin
+  if (props.m != null) s.margin = spacing(props.m);
+  if (props.mx != null) {
+    s.marginLeft = spacing(props.mx);
+    s.marginRight = spacing(props.mx);
+  }
+  if (props.my != null) {
+    s.marginTop = spacing(props.my);
+    s.marginBottom = spacing(props.my);
+  }
+  if (props.mt != null) s.marginTop = spacing(props.mt);
+  if (props.mr != null) s.marginRight = spacing(props.mr);
+  if (props.mb != null) s.marginBottom = spacing(props.mb);
+  if (props.ml != null) s.marginLeft = spacing(props.ml);
+
+  // surface
+  if (props.bg != null) s.backgroundColor = color(props.bg);
+  if (props.color != null) s.color = color(props.color);
+  if (props.radius != null) s.borderRadius = RADIUS[props.radius];
+  if (props.shadow != null) s.boxShadow = SHADOW[props.shadow];
+  if (props.border) {
+    const w = props.border === true ? 1 : props.border;
+    s.borderWidth = `${w}px`;
+    s.borderStyle = 'solid';
+    s.borderColor = color(props.borderColor ?? 'border');
+  } else if (props.borderColor != null) {
+    s.borderColor = color(props.borderColor);
+  }
+
+  // sizing
+  if (props.width != null) s.width = size(props.width);
+  if (props.height != null) s.height = heightSize(props.height);
+  if (props.minWidth != null) s.minWidth = size(props.minWidth);
+  if (props.maxWidth != null) s.maxWidth = size(props.maxWidth);
+  if (props.minHeight != null) s.minHeight = heightSize(props.minHeight);
+  if (props.maxHeight != null) s.maxHeight = heightSize(props.maxHeight);
+
+  // behavior
+  if (props.display != null) s.display = props.display;
+  if (props.overflow != null) s.overflow = props.overflow;
+  if (props.position != null) s.position = props.position;
+  if (props.textAlign != null) s.textAlign = props.textAlign;
+
+  // flex item
+  if (props.grow != null) s.flexGrow = flexNum(props.grow);
+  if (props.shrink != null) s.flexShrink = flexNum(props.shrink);
+  if (props.basis != null) s.flexBasis = size(props.basis);
+  if (props.alignSelf != null) s.alignSelf = props.alignSelf;
+
+  return s;
+}
+
+/** Split box style props out of a mixed props object. */
+export function splitBoxProps<T extends BoxStyleProps>(
+  props: T
+): { style: CSSProperties; rest: Omit<T, keyof BoxStyleProps> } {
+  const style = boxStyle(props);
+  const rest = { ...props } as Record<string, unknown>;
+  for (const k of BOX_KEYS) delete rest[k as string];
+  return { style, rest: rest as Omit<T, keyof BoxStyleProps> };
+}
+
+export { spacing as resolveSpace, size as resolveSize };

package/src/layout/link.stories.tsx

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from '../story-types';
+import { PrototypeModeProvider } from 'vinta-ui-composer-prototype-mode';
+
+import { Link } from './link';
+
+const meta = {
+  title: 'Layout/Link',
+  component: Link,
+  tags: ['autodocs'],
+  // Leaf: the label is editable text, the target is a plain string the platform
+  // resolves. `className`/`style` are never exposed (§6).
+  argTypes: {
+    children: { control: 'text', description: 'Link label' },
+    linkTo: {
+      control: 'text',
+      description: 'Target screen the platform resolves',
+    },
+  },
+  args: { children: 'View booking', linkTo: '/bookings' },
+} satisfies Meta<typeof Link>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default — no provider, so the context falls back to editor mode: INERT.
+ * This is what the composer canvas renders while you're editing.
+ */
+export const EditorInert: Story = {};
+
+/** Viewer mode with a host `navigate` — the only state that actually routes. */
+export const ViewerNavigating: Story = {
+  render: (args) => (
+    <PrototypeModeProvider
+      mode='viewer'
+      navigate={(to) => window.alert(`navigate → ${to}`)}
+    >
+      <Link {...args} />
+    </PrototypeModeProvider>
+  ),
+};
+
+/** Viewer mode, but the target is unreachable (archived/unpublished) → INERT. */
+export const ViewerUnreachable: Story = {
+  render: (args) => (
+    <PrototypeModeProvider
+      mode='viewer'
+      navigate={(to) => window.alert(`navigate → ${to}`)}
+      canNavigate={() => false}
+    >
+      <Link {...args} />
+    </PrototypeModeProvider>
+  ),
+};

package/src/layout/link.test.tsx

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { PrototypeModeProvider } from 'vinta-ui-composer-prototype-mode';
+
+import { Link } from './link';
+
+/**
+ * The inert-vs-navigating contract (§8). An inert link renders an <a> with no
+ * href, so it is not exposed as a link at all — asserting on the `link` role is
+ * the sharpest way to pin that.
+ */
+describe('Link', () => {
+  it('is inert with no provider (editor is the default)', () => {
+    render(<Link linkTo='/bookings'>View booking</Link>);
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    expect(screen.getByText('View booking')).not.toHaveAttribute('href');
+  });
+
+  it('is inert in editor mode even when a navigate is supplied', async () => {
+    const navigate = vi.fn();
+    render(
+      <PrototypeModeProvider mode='editor' navigate={navigate}>
+        <Link linkTo='/bookings'>View booking</Link>
+      </PrototypeModeProvider>
+    );
+    await userEvent.click(screen.getByText('View booking'));
+    expect(navigate).not.toHaveBeenCalled();
+  });
+
+  it('navigates via the host callback in viewer mode', async () => {
+    const navigate = vi.fn();
+    render(
+      <PrototypeModeProvider mode='viewer' navigate={navigate}>
+        <Link linkTo='/bookings'>View booking</Link>
+      </PrototypeModeProvider>
+    );
+    const link = screen.getByRole('link', { name: 'View booking' });
+    expect(link).toHaveAttribute('href', '/bookings');
+
+    await userEvent.click(link);
+    expect(navigate).toHaveBeenCalledWith('/bookings');
+  });
+
+  it('is inert in viewer mode when the target is unreachable', async () => {
+    const navigate = vi.fn();
+    render(
+      <PrototypeModeProvider
+        mode='viewer'
+        navigate={navigate}
+        canNavigate={() => false}
+      >
+        <Link linkTo='/archived'>Archived</Link>
+      </PrototypeModeProvider>
+    );
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    await userEvent.click(screen.getByText('Archived'));
+    expect(navigate).not.toHaveBeenCalled();
+  });
+
+  it('prefetches the target on hover', async () => {
+    const prefetch = vi.fn();
+    render(
+      <PrototypeModeProvider
+        mode='viewer'
+        navigate={vi.fn()}
+        prefetch={prefetch}
+      >
+        <Link linkTo='/bookings'>View booking</Link>
+      </PrototypeModeProvider>
+    );
+    await userEvent.hover(screen.getByRole('link'));
+    expect(prefetch).toHaveBeenCalledWith('/bookings');
+  });
+});

package/src/layout/link.tsx

@@ -0,0 +1,100 @@
+import * as React from 'react';
+import { usePrototypeMode } from 'vinta-ui-composer-prototype-mode';
+
+import { cn } from '../lib/utils';
+
+/**
+ * Link — the navigating primitive for the composer.
+ *
+ * The design system has no router of its own. This component reads the
+ * platform-owned `vinta-ui-composer-prototype-mode` context (a peer dependency
+ * kept EXTERNAL at bundle time and shimmed to the host's copy, exactly like
+ * `react`) to decide inert-vs-navigating:
+ *
+ *   · editor mode (the default when no provider is present) → INERT. The
+ *     composer canvas must never navigate when you click a link you're editing.
+ *   · viewer mode → calls the host-supplied `navigate(linkTo)`.
+ *   · viewer mode, but `canNavigate(linkTo)` is false (archived / unpublished /
+ *     missing target) → INERT.
+ *
+ * Inert renders an `<a>` WITHOUT `href`, which is not a link to the
+ * accessibility tree and is not focusable — the correct "looks like a link,
+ * does nothing" state, rather than a real link we cancel on click.
+ *
+ * Deliberately NOT re-exported from `./index` — the schedule app must keep
+ * using `next/link` for real routing. This primitive exists for prototypes
+ * rendered by the composer, and is reachable via the `./layout/link` subpath
+ * (which is also how the platform's synthesized barrel discovers it).
+ */
+export interface LinkProps extends Omit<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href'
+> {
+  /** Target screen. The platform resolves this; we never route on our own. */
+  linkTo: string;
+  children?: React.ReactNode;
+}
+
+const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  { linkTo, children, className, onClick, onMouseEnter, onFocus, ...props },
+  ref
+) {
+  const { mode, navigate, prefetch, canNavigate } = usePrototypeMode();
+
+  const reachable = canNavigate ? canNavigate(linkTo) : true;
+  const inert = mode !== 'viewer' || !navigate || !reachable;
+
+  const classes = cn(
+    'text-primary underline-offset-4 hover:underline',
+    inert && 'cursor-default',
+    className
+  );
+
+  if (inert) {
+    return (
+      <a ref={ref} className={classes} data-inert='' {...props}>
+        {children}
+      </a>
+    );
+  }
+
+  const warm = () => prefetch?.(linkTo);
+
+  return (
+    <a
+      ref={ref}
+      href={linkTo}
+      className={classes}
+      onMouseEnter={(e) => {
+        warm();
+        onMouseEnter?.(e);
+      }}
+      onFocus={(e) => {
+        warm();
+        onFocus?.(e);
+      }}
+      onClick={(e) => {
+        onClick?.(e);
+        // Let the browser own modified clicks (new tab/window) and anything a
+        // consumer already handled; otherwise hand off to the host's router.
+        if (
+          e.defaultPrevented ||
+          e.button !== 0 ||
+          e.metaKey ||
+          e.ctrlKey ||
+          e.shiftKey ||
+          e.altKey
+        ) {
+          return;
+        }
+        e.preventDefault();
+        navigate(linkTo);
+      }}
+      {...props}
+    >
+      {children}
+    </a>
+  );
+});
+
+export { Link };

package/src/layout/navbar.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from '../story-types';
+
+import { Navbar } from './navbar';
+import { Link } from './link';
+import { Button } from '../ui/button';
+
+const meta = {
+  title: 'Composition/Navbar',
+  component: Navbar,
+  tags: ['autodocs'],
+  // Three real ReactNode props → three slots (§3). `width` is the only editable
+  // scalar; `className`/`style` stay unexposed (§6).
+  argTypes: {
+    width: { control: 'inline-radio', options: ['contained', 'full'] },
+  },
+  args: { width: 'contained' },
+  parameters: {
+    layout: 'fullscreen',
+    puck: { slots: ['brand', 'links', 'actions'] },
+  },
+} satisfies Meta<typeof Navbar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Nav links use the DS `Link` primitive, which is inert here (no
+// PrototypeModeProvider ⇒ editor mode) — exactly how it renders on the
+// composer canvas.
+const Links = () => (
+  <>
+    {[
+      { label: 'Product', to: '/product' },
+      { label: 'Pricing', to: '/pricing' },
+      { label: 'Docs', to: '/docs' },
+    ].map((l) => (
+      <Link
+        key={l.label}
+        linkTo={l.to}
+        className='text-muted-foreground hover:bg-accent hover:text-foreground rounded-md px-3 py-2 text-sm font-medium no-underline hover:no-underline'
+      >
+        {l.label}
+      </Link>
+    ))}
+  </>
+);
+
+const NavbarDemo = (args: Partial<Parameters<typeof Navbar>[0]>) => (
+  <Navbar
+    {...args}
+    links={<Links />}
+    actions={
+      <>
+        <Button variant='ghost' size='sm'>
+          Log in
+        </Button>
+        <Button size='sm'>Sign up</Button>
+      </>
+    }
+  />
+);
+
+export const Default: Story = {
+  render: (args) => <NavbarDemo {...args} />,
+};
+
+// Below @3xl links + actions collapse into a hamburger drawer.
+export const Mobile: Story = {
+  globals: { viewport: { value: 'mobile' } },
+  render: (args) => <NavbarDemo {...args} />,
+};