vinta-schedule-design-system 0.1.0

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "vinta-schedule-design-system",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    "./ui/*": "./src/ui/*.tsx",
+    "./layout": "./src/layout/index.ts",
+    "./layout/*": "./src/layout/*.tsx",
+    "./lib/utils": "./src/lib/utils.ts",
+    "./story-types": "./src/story-types.ts",
+    "./styles.css": "./dist/styles.css",
+    "./styles/tokens.css": "./src/styles/tokens.css",
+    "./styles/globals.css": "./src/styles/globals.css"
+  },
+  "files": [
+    "src/ui",
+    "src/layout",
+    "src/lib",
+    "src/styles",
+    "src/story-types.ts",
+    "dist",
+    "components.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build",
+    "build:css": "tailwindcss -i ./src/styles/build.css -o ./dist/styles.css",
+    "build": "pnpm run build:css",
+    "check:contract": "node ./scripts/check-contract.mjs",
+    "prepack": "pnpm run build:css"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vinta-ui-composer-prototype-mode": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vinta-ui-composer-prototype-mode": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@radix-ui/react-accordion": "^1.2.12",
+    "@radix-ui/react-alert-dialog": "^1.1.15",
+    "@radix-ui/react-avatar": "^1.1.11",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-navigation-menu": "^1.2.14",
+    "@radix-ui/react-progress": "^1.1.8",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "embla-carousel-react": "^8.6.0",
+    "input-otp": "^1.4.2",
+    "lucide-react": "^1.17.0",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.5.0",
+    "react-hook-form": "^7.77.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "vaul": "^1.1.2"
+  },
+  "devDependencies": {
+    "@storybook/addon-a11y": "^10.4.2",
+    "@storybook/addon-docs": "^10.4.2",
+    "@storybook/addon-themes": "^10.4.2",
+    "@storybook/react-vite": "^10.4.2",
+    "@tailwindcss/cli": "^4.3.0",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "esbuild": "^0.28.1",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "storybook": "^10.4.2",
+    "tailwindcss": "^4.3.0",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3",
+    "vinta-ui-composer-prototype-mode": "^0.1.0",
+    "vitest": "^4.1.8"
+  }
+}

package/src/layout/app-shell.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import * as React from 'react';
+import { Menu } from 'lucide-react';
+
+import { cn } from '../lib/utils';
+import { Button } from '../ui/button';
+import { Sheet, SheetContent, SheetTitle, SheetTrigger } from '../ui/sheet';
+import { Box } from './box';
+import { Flex } from './flex';
+import { Container } from './container';
+
+/**
+ * AppShell — the authenticated application frame. Composes an optional sidebar
+ * and topbar around a scrollable main region. `width` controls whether the page
+ * body is capped to the contained 1200px column or runs full-bleed.
+ *
+ * Responsive: the shell is an `@container/app`. Above @4xl (896px) the sidebar
+ * is docked on the left; below that it collapses into a slide-over drawer
+ * toggled by a hamburger (injected into the topbar's `leading` slot, or shown
+ * in a thin mobile bar when there's no topbar). The page body is an
+ * `@container/content` so content reacts to its own width, not the viewport.
+ *
+ * Covers every generic page layout by toggling props:
+ *   sidebar + topbar · topbar only · no bars  ×  contained | full
+ */
+export interface AppShellProps {
+  sidebar?: React.ReactNode;
+  topbar?: React.ReactNode;
+  width?: 'contained' | 'full';
+  className?: string;
+  /** Extra classes on the <Container> wrapping page content. */
+  contentClassName?: string;
+  children?: React.ReactNode;
+}
+
+function AppShell({
+  sidebar,
+  topbar,
+  width = 'contained',
+  className,
+  contentClassName,
+  children,
+}: AppShellProps) {
+  const trigger = sidebar ? (
+    <SheetTrigger asChild>
+      <Button
+        variant='ghost'
+        size='icon'
+        aria-label='Open navigation'
+        className='-ml-1 shrink-0 @4xl/app:hidden'
+      >
+        <Menu />
+      </Button>
+    </SheetTrigger>
+  ) : null;
+
+  // Inject the mobile trigger into the topbar's leading slot when possible so
+  // the hamburger sits inline with the page title.
+  const topbarNode =
+    topbar && trigger && React.isValidElement(topbar)
+      ? React.cloneElement(
+          topbar as React.ReactElement<{ leading?: React.ReactNode }>,
+          { leading: trigger }
+        )
+      : topbar;
+
+  const shell = (
+    <Flex
+      height='screen'
+      width='full'
+      overflow='hidden'
+      bg='background'
+      color='foreground'
+      className={cn('@container/app', className)}
+    >
+      {/* Docked sidebar — display:contents above @4xl so the aside is a direct
+          flex child; fully hidden below (the drawer takes over). */}
+      {sidebar ? (
+        <div className='hidden @4xl/app:contents'>{sidebar}</div>
+      ) : null}
+
+      <Flex direction='column' grow={1} minWidth={0} overflow='hidden'>
+        {topbarNode}
+
+        {/* Mobile bar with just the trigger, for the no-topbar layouts. */}
+        {sidebar && !topbar ? (
+          <div className='border-border flex h-14 shrink-0 items-center border-b px-4 @4xl/app:hidden'>
+            {trigger}
+          </div>
+        ) : null}
+
+        <Box as='main' grow={1} overflow='auto' className='@container/content'>
+          <Container width={width} py={8} className={contentClassName}>
+            {children}
+          </Container>
+        </Box>
+      </Flex>
+    </Flex>
+  );
+
+  if (!sidebar) return shell;
+
+  return (
+    <Sheet>
+      {shell}
+      <SheetContent side='left' className='w-[244px] p-0'>
+        <SheetTitle className='sr-only'>Navigation</SheetTitle>
+        {sidebar}
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+export { AppShell };

package/src/layout/app-topbar.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '../story-types';
+import { CalendarPlus } from 'lucide-react';
+
+import { AppTopbar } from './app-topbar';
+import { Button } from '../ui/button';
+
+const meta = {
+  title: 'Composition/AppTopbar',
+  component: AppTopbar,
+  tags: ['autodocs'],
+  // `title` / `subtitle` are ReactNode but render as plain copy → text controls.
+  // `actions` and `leading` are composed content → slots (§3). `className` /
+  // `style` stay unexposed (§6).
+  argTypes: {
+    title: { control: 'text', description: 'Page title' },
+    subtitle: {
+      control: 'text',
+      description: 'Secondary line under the title',
+    },
+    showSearch: { control: 'boolean' },
+    searchPlaceholder: { control: 'text' },
+    sync: {
+      control: 'select',
+      options: ['synced', 'syncing'],
+      description: 'Sync-status pill (omit to hide it)',
+    },
+  },
+  args: { title: 'Calendar', subtitle: 'This week · 3 bookings' },
+  parameters: {
+    layout: 'fullscreen',
+    puck: { slots: ['actions', 'leading'] },
+  },
+} satisfies Meta<typeof AppTopbar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Collapses to an icon button at narrow topbar widths.
+const NewBookingAction = () => (
+  <>
+    <Button
+      size='icon'
+      aria-label='New booking'
+      className='shrink-0 @3xl/topbar:hidden'
+    >
+      <CalendarPlus />
+    </Button>
+    <Button size='sm' className='hidden shrink-0 @3xl/topbar:inline-flex'>
+      <CalendarPlus />
+      New booking
+    </Button>
+  </>
+);
+
+export const Default: Story = {
+  render: (args) => <AppTopbar {...args} actions={<NewBookingAction />} />,
+};
+
+export const Syncing: Story = {
+  args: { sync: 'syncing', subtitle: 'Refreshing connected calendars' },
+  render: (args) => <AppTopbar {...args} />,
+};
+
+export const NoSearch: Story = {
+  args: { showSearch: false, sync: null },
+  render: (args) => <AppTopbar {...args} />,
+};
+
+// At narrow widths: search → icon button, action → icon button, sync pill
+// stays. Title shrinks.
+export const Mobile: Story = {
+  globals: { viewport: { value: 'mobile' } },
+  render: (args) => <AppTopbar {...args} actions={<NewBookingAction />} />,
+};

package/src/layout/app-topbar.tsx

@@ -0,0 +1,145 @@
+'use client';
+
+import * as React from 'react';
+import { Check, RefreshCw, Search, X } from 'lucide-react';
+
+import { cn } from '../lib/utils';
+import { Badge } from '../ui/badge';
+import { Button } from '../ui/button';
+import { Input } from '../ui/input';
+
+type SyncState = 'synced' | 'syncing';
+
+/**
+ * AppTopbar — in-app header bar. Page title + subtitle on the left, optional
+ * search, a sync-status pill, and action slot on the right. Sticky + blurred.
+ */
+export interface AppTopbarProps extends Omit<
+  React.HTMLAttributes<HTMLElement>,
+  'title'
+> {
+  /** Optional — omit for a minimal bar (e.g. just a leading trigger + actions). */
+  title?: React.ReactNode;
+  subtitle?: React.ReactNode;
+  actions?: React.ReactNode;
+  /** Leading slot — e.g. a mobile nav trigger injected by AppShell. */
+  leading?: React.ReactNode;
+  showSearch?: boolean;
+  searchPlaceholder?: string;
+  sync?: SyncState | null;
+}
+
+const AppTopbar = React.forwardRef<HTMLElement, AppTopbarProps>(
+  function AppTopbar(
+    {
+      className,
+      title,
+      subtitle,
+      actions,
+      leading,
+      showSearch = true,
+      searchPlaceholder = 'Search people & resources',
+      sync = 'synced',
+      ...props
+    },
+    ref
+  ) {
+    const [searchOpen, setSearchOpen] = React.useState(false);
+    return (
+      <header
+        ref={ref}
+        className={cn(
+          // @container/topbar so the inner controls react to the bar's own
+          // width, not the viewport — they collapse first when a sidebar eats
+          // the horizontal space. `relative` anchors the search overlay.
+          'border-border bg-background/80 @container/topbar relative sticky top-0 z-20 flex h-16 shrink-0 items-center gap-3 border-b px-4 backdrop-blur @2xl/topbar:gap-4 @2xl/topbar:px-6',
+          className
+        )}
+        {...props}
+      >
+        {leading}
+
+        {title || subtitle ? (
+          <div className='min-w-0'>
+            {title ? (
+              <h1 className='truncate text-[15px] leading-tight font-semibold @2xl/topbar:text-[17px]'>
+                {title}
+              </h1>
+            ) : null}
+            {subtitle ? (
+              <p className='text-muted-foreground truncate text-[12.5px] leading-tight'>
+                {subtitle}
+              </p>
+            ) : null}
+          </div>
+        ) : null}
+
+        <div className='flex-1' />
+
+        {showSearch ? (
+          <>
+            {/* Narrow: collapse the field to an icon button that expands the
+                full-width search overlay. */}
+            <Button
+              variant='ghost'
+              size='icon'
+              aria-label={searchPlaceholder}
+              onClick={() => setSearchOpen(true)}
+              className='shrink-0 @3xl/topbar:hidden'
+            >
+              <Search />
+            </Button>
+            <div className='relative hidden w-64 @3xl/topbar:block'>
+              <Search className='text-muted-foreground pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2' />
+              <Input className='pl-9' placeholder={searchPlaceholder} />
+            </div>
+          </>
+        ) : null}
+
+        {sync ? (
+          <Badge
+            variant={sync === 'synced' ? 'success' : 'info'}
+            className='shrink-0'
+          >
+            {sync === 'synced' ? (
+              <Check />
+            ) : (
+              <RefreshCw className='animate-spin' />
+            )}
+            <span className='hidden @xl/topbar:inline'>
+              {sync === 'synced' ? 'All synced' : 'Syncing…'}
+            </span>
+          </Badge>
+        ) : null}
+
+        {actions}
+
+        {/* Expanded search — full-width, covers the bar. Autofocused; X closes. */}
+        {showSearch && searchOpen ? (
+          <div className='bg-background absolute inset-0 z-10 flex items-center gap-2 px-4 @2xl/topbar:px-6'>
+            <Search className='text-muted-foreground size-4 shrink-0' />
+            <Input
+              autoFocus
+              placeholder={searchPlaceholder}
+              onKeyDown={(e) => {
+                if (e.key === 'Escape') setSearchOpen(false);
+              }}
+              className='h-9 flex-1 border-0 bg-transparent shadow-none focus-visible:ring-0'
+            />
+            <Button
+              variant='ghost'
+              size='icon'
+              aria-label='Close search'
+              onClick={() => setSearchOpen(false)}
+              className='shrink-0'
+            >
+              <X />
+            </Button>
+          </div>
+        ) : null}
+      </header>
+    );
+  }
+);
+
+export { AppTopbar };

package/src/layout/auth-layout.tsx

@@ -0,0 +1,45 @@
+import * as React from 'react';
+
+import { Box } from './box';
+import { Flex } from './flex';
+import { Center } from './center';
+
+/**
+ * AuthLayout — public authentication page shell: a top navbar above a single
+ * centered column. `variant` only changes how wide that column is:
+ *   single     → 448px (one-column forms)
+ *   two-column → 768px (a double-width container that splits into two columns
+ *                internally — e.g. social sign-in beside the form).
+ */
+export interface AuthLayoutProps {
+  navbar?: React.ReactNode;
+  variant?: 'single' | 'two-column';
+  className?: string;
+  children?: React.ReactNode;
+}
+
+function AuthLayout({
+  navbar,
+  variant = 'single',
+  className,
+  children,
+}: AuthLayoutProps) {
+  return (
+    <Flex
+      direction='column'
+      minHeight='screen'
+      bg='background'
+      color='foreground'
+      className={className}
+    >
+      {navbar}
+      <Center as='main' grow={1} px={4} py={12}>
+        <Box width='full' maxWidth={variant === 'two-column' ? 768 : 448}>
+          {children}
+        </Box>
+      </Center>
+    </Flex>
+  );
+}
+
+export { AuthLayout };

package/src/layout/box.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '../story-types';
+
+import { Box } from './box';
+
+const meta = {
+  title: 'Layout/Box',
+  component: Box,
+  tags: ['autodocs'],
+  // Box's props are the shared BoxStyleProps vocabulary (layout-style.ts). Only
+  // a meaningful subset is exposed — spacing, surface, sizing. `className` /
+  // `style` are deliberately NOT editable (§6), and `children` is the composed
+  // content slot (§3) so it must not appear in argTypes (SLOT_ARGTYPE_COLLISION).
+  argTypes: {
+    p: { control: 'select', options: [0, 2, 4, 6, 8, 12] },
+    px: { control: 'select', options: [0, 2, 4, 6, 8, 12] },
+    py: { control: 'select', options: [0, 2, 4, 6, 8, 12] },
+    radius: {
+      control: 'select',
+      options: ['none', 'sm', 'md', 'lg', 'xl', '2xl', 'full'],
+    },
+    shadow: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    bg: {
+      control: 'select',
+      options: ['background', 'card', 'muted', 'accent', 'primary'],
+    },
+    color: {
+      control: 'select',
+      options: [
+        'foreground',
+        'muted-foreground',
+        'primary',
+        'primary-foreground',
+        'vinta-700',
+      ],
+    },
+    border: { control: 'boolean' },
+    width: { control: 'select', options: [180, 320, 480, 'full'] },
+    textAlign: {
+      control: 'inline-radio',
+      options: ['left', 'center', 'right'],
+    },
+  },
+  args: {
+    p: 6,
+    bg: 'card',
+    radius: 'lg',
+    shadow: 'sm',
+    border: true,
+  },
+  parameters: { puck: { slots: ['children'] } },
+} satisfies Meta<typeof Box>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: (args) => <Box {...args}>Box — styled by props, no classes.</Box>,
+};
+
+export const Surfaces: Story = {
+  render: () => (
+    <Box display='flex' style={{ gap: '1rem', flexWrap: 'wrap' }}>
+      <Box p={6} bg='card' radius='lg' shadow='sm' border width={180}>
+        card · shadow sm
+      </Box>
+      <Box p={6} bg='muted' radius='lg' width={180}>
+        muted
+      </Box>
+      <Box
+        p={6}
+        bg='primary'
+        color='primary-foreground'
+        radius='lg'
+        width={180}
+      >
+        primary
+      </Box>
+      <Box p={6} bg='vinta-50' color='vinta-700' radius='xl' width={180}>
+        vinta-50 / 700
+      </Box>
+    </Box>
+  ),
+};

package/src/layout/box.tsx

@@ -0,0 +1,34 @@
+import * as React from 'react';
+
+import { cn } from '../lib/utils';
+import { boxStyle, splitBoxProps, type BoxStyleProps } from './layout-style';
+
+export interface BoxProps
+  extends BoxStyleProps, Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+  /** Element/component to render. Defaults to `div`. */
+  as?: React.ElementType;
+}
+
+/**
+ * Box — the primitive every other layout component builds on. A styled element
+ * driven entirely by token props (padding, margin, bg, radius, shadow, sizing…)
+ * instead of utility classes.
+ *
+ *   <Box p={4} bg="card" radius="lg" shadow="sm" border>…</Box>
+ */
+const Box = React.forwardRef<HTMLElement, BoxProps>(function Box(
+  { as: Comp = 'div', className, style, ...props },
+  ref
+) {
+  const { style: resolved, rest } = splitBoxProps(props);
+  return (
+    <Comp
+      ref={ref}
+      className={cn(className)}
+      style={{ ...resolved, ...style }}
+      {...rest}
+    />
+  );
+});
+
+export { Box, boxStyle };

package/src/layout/center.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+import { Flex, type FlexProps } from './flex';
+
+/**
+ * Center — centers its children on both axes. Pass `width`/`height`/`minHeight`
+ * to size the centering area (e.g. `minHeight="screen"`).
+ */
+const Center = React.forwardRef<
+  HTMLElement,
+  Omit<FlexProps, 'align' | 'justify'>
+>(function Center({ inline, ...props }, ref) {
+  return (
+    <Flex
+      ref={ref}
+      align='center'
+      justify='center'
+      inline={inline}
+      {...props}
+    />
+  );
+});
+
+export { Center };

package/src/layout/container.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '../story-types';
+
+import { Container } from './container';
+
+const meta = {
+  title: 'Layout/Container',
+  component: Container,
+  tags: ['autodocs'],
+  // `width` is Container's own prop; the rest come from BoxStyleProps, which
+  // Container extends. `children` is the composed content slot (§3).
+  argTypes: {
+    width: { control: 'inline-radio', options: ['contained', 'prose', 'full'] },
+    py: { control: 'select', options: [0, 2, 4, 6, 8, 12, 16] },
+    bg: {
+      control: 'select',
+      options: ['background', 'card', 'muted', 'accent'],
+    },
+  },
+  args: { width: 'contained' },
+  parameters: { layout: 'fullscreen', puck: { slots: ['children'] } },
+} satisfies Meta<typeof Container>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const Demo = () => (
+  <div className='border-primary/40 bg-accent/40 text-muted-foreground rounded-lg border border-dashed p-6 text-center text-sm'>
+    Container content
+  </div>
+);
+
+export const Contained: Story = {
+  args: { width: 'contained' },
+  render: (args) => (
+    <div className='bg-muted/40 py-8'>
+      <Container {...args}>
+        <Demo />
+      </Container>
+    </div>
+  ),
+};
+
+export const Prose: Story = { ...Contained, args: { width: 'prose' } };
+export const Full: Story = { ...Contained, args: { width: 'full' } };