@otfdashkit/ui 0.1.0

package/src/layout/PageContainer.tsx

@@ -0,0 +1,40 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+/**
+ * PageContainer — responsive max-width ladder.
+ */
+export const PageContainer = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-container"
+    className={cn(
+      'px-4 w-full min-w-[320px] mx-auto',
+      'md:max-w-[760px] lg:max-w-[900px] xl:max-w-[1160px]',
+      className
+    )}
+    {...props}
+  />
+))
+PageContainer.displayName = 'PageContainer'
+
+export const PageMain = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-main"
+    role="main"
+    className={cn(
+      'px-4 w-full min-w-[320px] mx-auto',
+      'md:max-w-[760px] lg:max-w-[900px] xl:max-w-[1160px]',
+      className
+    )}
+    {...props}
+  />
+))
+PageMain.displayName = 'PageMain'

package/src/layout/PageLayout.tsx

@@ -0,0 +1,55 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+/** Full-viewport flex column layout */
+export const PageLayout = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-layout"
+    className={cn('flex min-h-screen flex-col bg-background text-foreground', className)}
+    {...props}
+  />
+))
+PageLayout.displayName = 'PageLayout'
+
+export interface PageHeaderProps {
+  title?: React.ReactNode
+  description?: React.ReactNode
+  actions?: React.ReactNode
+  back?: React.ReactNode
+  children?: React.ReactNode
+  className?: string
+}
+
+/** Page header: title + optional description + actions row */
+export const PageHeader = React.forwardRef<HTMLDivElement, PageHeaderProps>(
+  ({ className, title, description, actions, back, children }, ref) => (
+    <div
+      ref={ref}
+      data-slot="page-header"
+      className={cn('flex flex-col gap-1 pb-6', className)}
+    >
+      {back && <div className="mb-2">{back}</div>}
+      <div className="flex items-start justify-between gap-4">
+        <div className="space-y-1">
+          {title && (
+            <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+              {title}
+            </h1>
+          )}
+          {description && (
+            <p className="text-sm text-muted-foreground">{description}</p>
+          )}
+        </div>
+        {actions && (
+          <div className="flex items-center gap-2 shrink-0">{actions}</div>
+        )}
+      </div>
+      {children}
+    </div>
+  )
+)
+PageHeader.displayName = 'PageHeader'

package/src/layout/index.ts

@@ -0,0 +1,2 @@
+export * from './PageContainer'
+export * from './PageLayout'

package/src/layouts/AppShell/AppShell.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { AppShell } from './AppShell'
+
+// TODO: add all variants
+const meta: Meta<typeof AppShell> = {
+  title: 'Layouts/AppShell',
+  component: AppShell,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof AppShell>
+
+export const Default: Story = {}

package/src/layouts/AppShell/AppShell.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { AppShell } from './AppShell'
+
+// TODO: add full a11y + variant tests
+describe('AppShell', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<AppShell />)).not.toThrow()
+  })
+})

package/src/layouts/AppShell/AppShell.tsx

@@ -0,0 +1,129 @@
+'use client'
+
+import React from 'react'
+import { Menu, X } from 'lucide-react'
+import { cn } from '../utils/cn'
+
+interface AppShellCtxValue {
+  collapsed: boolean
+  setCollapsed: (v: boolean) => void
+  mobileOpen: boolean
+  setMobileOpen: (v: boolean) => void
+}
+
+const AppShellCtx = React.createContext<AppShellCtxValue>({
+  collapsed: false,
+  setCollapsed: () => {},
+  mobileOpen: false,
+  setMobileOpen: () => {},
+})
+
+export const useAppShell = () => React.useContext(AppShellCtx)
+
+export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
+  defaultCollapsed?: boolean
+}
+
+export const AppShell = React.forwardRef<HTMLDivElement, AppShellProps>(
+  ({ className, defaultCollapsed = false, children, ...props }, ref) => {
+    const [collapsed, setCollapsed] = React.useState(defaultCollapsed)
+    const [mobileOpen, setMobileOpen] = React.useState(false)
+
+    // Close mobile sidebar on nav link clicks inside the shell
+    React.useEffect(() => {
+      const handleClick = (e: MouseEvent) => {
+        const target = e.target as HTMLElement
+        if (target.closest('a[href]') || target.closest('[data-mobile-close]')) {
+          setMobileOpen(false)
+        }
+      }
+      document.addEventListener('click', handleClick)
+      return () => document.removeEventListener('click', handleClick)
+    }, [])
+
+    return (
+      <AppShellCtx.Provider value={{ collapsed, setCollapsed, mobileOpen, setMobileOpen }}>
+        <div
+          ref={ref}
+          className={cn('flex h-screen w-full overflow-hidden bg-background', className)}
+          {...props}
+        >
+          {/* Mobile backdrop — rendered inside AppShell so it doesn't break SSR */}
+          {mobileOpen && (
+            <div
+              className="fixed inset-0 z-40 bg-black/50 md:hidden"
+              onClick={() => setMobileOpen(false)}
+            />
+          )}
+          {children}
+        </div>
+      </AppShellCtx.Provider>
+    )
+  }
+)
+AppShell.displayName = 'AppShell'
+
+/**
+ * Sidebar wrapper.
+ * On MOBILE  → hidden (display: none) by default; shown as a fixed overlay when mobileOpen=true.
+ * On DESKTOP → always visible as a normal flex child.
+ *
+ * ALWAYS wrap <Sidebar> in <AppShellSidebar> — never put <Sidebar> directly in <AppShell>.
+ * Without this wrapper the sidebar is visible on all screen sizes.
+ */
+export const AppShellSidebar = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => {
+    const { mobileOpen } = useAppShell()
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'shrink-0 h-full',
+          // Mobile: hidden by default; shows as fixed overlay when open
+          mobileOpen
+            ? 'fixed inset-y-0 left-0 z-50 flex'
+            : 'hidden md:flex',
+          // Desktop: always visible as a normal relative element
+          'md:relative',
+          className
+        )}
+        {...props}
+      />
+    )
+  }
+)
+AppShellSidebar.displayName = 'AppShellSidebar'
+
+export const AppShellMain = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('flex-1 min-w-0 flex flex-col overflow-auto', className)} {...props} />
+  )
+)
+AppShellMain.displayName = 'AppShellMain'
+
+/**
+ * Hamburger/close button — place in your mobile header bar (md:hidden).
+ * Toggles the sidebar overlay on mobile.
+ */
+export const MobileSidebarTrigger = React.forwardRef<HTMLButtonElement, React.ButtonHTMLAttributes<HTMLButtonElement>>(
+  ({ className, ...props }, ref) => {
+    const { mobileOpen, setMobileOpen } = useAppShell()
+    return (
+      <button
+        ref={ref}
+        onClick={() => setMobileOpen(!mobileOpen)}
+        aria-label={mobileOpen ? 'Close menu' : 'Open menu'}
+        className={cn(
+          'md:hidden inline-flex items-center justify-center rounded-md p-2',
+          'text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          className
+        )}
+        {...props}
+      >
+        {mobileOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}
+      </button>
+    )
+  }
+)
+MobileSidebarTrigger.displayName = 'MobileSidebarTrigger'

package/src/layouts/AppShell/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './AppShell'

package/src/layouts/Container/Container.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Container } from './Container'
+
+// TODO: add all variants
+const meta: Meta<typeof Container> = {
+  title: 'Layouts/Container',
+  component: Container,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Container>
+
+export const Default: Story = {}

package/src/layouts/Container/Container.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { Container } from './Container'
+
+// TODO: add full a11y + variant tests
+describe('Container', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<Container />)).not.toThrow()
+  })
+})

package/src/layouts/Container/Container.tsx

@@ -0,0 +1,33 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+type ContainerSize = 'sm' | 'md' | 'lg' | 'xl' | 'full'
+
+const sizeMap: Record<ContainerSize, string> = {
+  sm: 'max-w-screen-sm',
+  md: 'max-w-screen-md',
+  lg: 'max-w-screen-lg',
+  xl: 'max-w-screen-xl',
+  full: 'max-w-full',
+}
+
+export interface ContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  size?: ContainerSize
+  noPadding?: boolean
+}
+
+export const Container = React.forwardRef<HTMLDivElement, ContainerProps>(
+  ({ className, size = 'lg', noPadding = false, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'mx-auto w-full',
+        sizeMap[size],
+        !noPadding && 'px-4 sm:px-6 lg:px-8',
+        className
+      )}
+      {...props}
+    />
+  )
+)
+Container.displayName = 'Container'

package/src/layouts/Container/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './Container'

package/src/layouts/Navbar/Navbar.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Navbar } from './Navbar'
+
+// TODO: add all variants
+const meta: Meta<typeof Navbar> = {
+  title: 'Layouts/Navbar',
+  component: Navbar,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Navbar>
+
+export const Default: Story = {}

package/src/layouts/Navbar/Navbar.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { Navbar } from './Navbar'
+
+// TODO: add full a11y + variant tests
+describe('Navbar', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<Navbar />)).not.toThrow()
+  })
+})

package/src/layouts/Navbar/Navbar.tsx

@@ -0,0 +1,60 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+export interface NavbarProps extends React.HTMLAttributes<HTMLElement> {
+  sticky?: boolean
+  border?: boolean
+}
+
+export const Navbar = React.forwardRef<HTMLElement, NavbarProps>(
+  ({ className, sticky = false, border = true, ...props }, ref) => (
+    <nav
+      ref={ref}
+      className={cn(
+        'z-40 w-full h-14 flex items-center bg-[hsl(var(--background))]',
+        sticky && 'sticky top-0',
+        border && 'border-b border-[hsl(var(--border))]',
+        className
+      )}
+      {...props}
+    />
+  )
+)
+Navbar.displayName = 'Navbar'
+
+export const NavbarBrand = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('flex items-center gap-2 px-4 shrink-0', className)} {...props} />
+  )
+)
+NavbarBrand.displayName = 'NavbarBrand'
+
+type Align = 'start' | 'center' | 'end'
+
+const alignMap: Record<Align, string> = {
+  start: 'justify-start',
+  center: 'justify-center flex-1',
+  end: 'justify-end ml-auto',
+}
+
+export interface NavbarContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  align?: Align
+}
+
+export const NavbarContent = React.forwardRef<HTMLDivElement, NavbarContentProps>(
+  ({ className, align = 'start', ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('flex items-center gap-1 px-2', alignMap[align], className)}
+      {...props}
+    />
+  )
+)
+NavbarContent.displayName = 'NavbarContent'
+
+export const NavbarItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('flex items-center', className)} {...props} />
+  )
+)
+NavbarItem.displayName = 'NavbarItem'

package/src/layouts/Navbar/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './Navbar'

package/src/layouts/Page/Page.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Page } from './Page'
+
+// TODO: add all variants
+const meta: Meta<typeof Page> = {
+  title: 'Layouts/Page',
+  component: Page,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Page>
+
+export const Default: Story = {}

package/src/layouts/Page/Page.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { Page } from './Page'
+
+// TODO: add full a11y + variant tests
+describe('Page', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<Page />)).not.toThrow()
+  })
+})

package/src/layouts/Page/Page.tsx

@@ -0,0 +1,61 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+export interface PageProps extends React.HTMLAttributes<HTMLDivElement> {
+  maxWidth?: string
+}
+
+export const Page = React.forwardRef<HTMLDivElement, PageProps>(
+  ({ className, maxWidth, style, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('flex flex-col min-h-full w-full', className)}
+      style={{ maxWidth, ...style }}
+      {...props}
+    />
+  )
+)
+Page.displayName = 'Page'
+
+export const PageHeader = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('flex items-start justify-between gap-4 px-6 py-4 border-b border-[hsl(var(--border))]', className)}
+      {...props}
+    />
+  )
+)
+PageHeader.displayName = 'PageHeader'
+
+export const PageTitle = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => (
+    <h1
+      ref={ref}
+      className={cn('text-2xl font-semibold tracking-tight text-[hsl(var(--foreground))]', className)}
+      {...props}
+    />
+  )
+)
+PageTitle.displayName = 'PageTitle'
+
+export const PageDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, ...props }, ref) => (
+    <p ref={ref} className={cn('text-sm text-[hsl(var(--muted-foreground))] mt-1', className)} {...props} />
+  )
+)
+PageDescription.displayName = 'PageDescription'
+
+export const PageActions = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('flex items-center gap-2 shrink-0', className)} {...props} />
+  )
+)
+PageActions.displayName = 'PageActions'
+
+export const PageBody = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('flex-1 p-6 flex flex-col gap-6', className)} {...props} />
+  )
+)
+PageBody.displayName = 'PageBody'

package/src/layouts/Page/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './Page'

package/src/layouts/ResizeBox/ResizeBox.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { ResizeBox } from './ResizeBox'
+
+// TODO: add all variants
+const meta: Meta<typeof ResizeBox> = {
+  title: 'Layouts/ResizeBox',
+  component: ResizeBox,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof ResizeBox>
+
+export const Default: Story = {}

package/src/layouts/ResizeBox/ResizeBox.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { ResizeBox } from './ResizeBox'
+
+// TODO: add full a11y + variant tests
+describe('ResizeBox', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<ResizeBox />)).not.toThrow()
+  })
+})

package/src/layouts/ResizeBox/ResizeBox.tsx

@@ -0,0 +1,45 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+export interface ResizeBoxProps extends React.HTMLAttributes<HTMLDivElement> {
+  resize?: 'horizontal' | 'vertical' | 'both' | 'none'
+  minWidth?: number
+  minHeight?: number
+}
+
+export const ResizeBox = React.forwardRef<HTMLDivElement, ResizeBoxProps>(
+  ({ className, resize = 'both', minWidth = 100, minHeight = 100, style, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('overflow-auto relative', className)}
+      style={{ resize, minWidth, minHeight, ...style }}
+      {...props}
+    />
+  )
+)
+ResizeBox.displayName = 'ResizeBox'
+
+const HandleIcon = () => (
+  <svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden>
+    <path d="M8 2L2 8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    <path d="M8 5L5 8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    <path d="M8 8L8 8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+  </svg>
+)
+
+export const ResizeHandle = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'absolute bottom-0 right-0 w-5 h-5 flex items-center justify-center',
+        'cursor-se-resize text-[hsl(var(--muted-foreground))] opacity-50 hover:opacity-100 transition-opacity',
+        className
+      )}
+      {...props}
+    >
+      <HandleIcon />
+    </div>
+  )
+)
+ResizeHandle.displayName = 'ResizeHandle'

package/src/layouts/ResizeBox/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './ResizeBox'

package/src/layouts/Sidebar/Sidebar.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Sidebar } from './Sidebar'
+
+// TODO: add all variants
+const meta: Meta<typeof Sidebar> = {
+  title: 'Layouts/Sidebar',
+  component: Sidebar,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Sidebar>
+
+export const Default: Story = {}

package/src/layouts/Sidebar/Sidebar.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { Sidebar } from './Sidebar'
+
+// TODO: add full a11y + variant tests
+describe('Sidebar', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<Sidebar />)).not.toThrow()
+  })
+})