velocis 1.0.1 → 1.1.0

package/docs/dropdown1.md

@@ -0,0 +1,154 @@
+# Dropdown1 (`velocis/dropdown1`)
+
+Flexible action menus with optional nested sub-menus. Compose items freely — use `SubMenu` only when you need nested options.
+
+Use **Dropdown1** for action menus and nested menu lists. Use [`velocis/dialog1`](./dialog1.md) `popover` variant for arbitrary panel content (forms, rich layouts).
+
+## Import
+
+```tsx
+'use client';
+
+import { Dropdown1, useDropdown1 } from 'velocis/dropdown1';
+```
+
+## When to use
+
+| Scenario | Use |
+|----------|-----|
+| Simple action menu | `Dropdown1` + `Dropdown1.Item` |
+| Menu with nested options | Add `Dropdown1.SubMenu` around sub-items |
+| Controlled open state | `useDropdown1()` hook |
+| Rich panel beside trigger | `Dialog1` popover → [dialog1.md](./dialog1.md) |
+| Native form select | `FormSelect` → [forms.md](./forms.md) |
+
+## Quick setup — simple menu
+
+```tsx
+<Dropdown1 trigger={<span>Actions</span>}>
+  <Dropdown1.Item onClick={() => console.log('edit')}>Edit</Dropdown1.Item>
+  <Dropdown1.Item onClick={() => console.log('delete')}>Delete</Dropdown1.Item>
+</Dropdown1>
+```
+
+## Quick setup — with sub-menu
+
+```tsx
+<Dropdown1 trigger={<span>Menu</span>}>
+  <Dropdown1.Item onClick={() => console.log('item 1')}>Item 1</Dropdown1.Item>
+  <Dropdown1.SubMenu trigger="More">
+    <Dropdown1.Item onClick={() => console.log('sub 1')}>Sub 1</Dropdown1.Item>
+    <Dropdown1.Item onClick={() => console.log('sub 2')}>Sub 2</Dropdown1.Item>
+  </Dropdown1.SubMenu>
+</Dropdown1>
+```
+
+No `SubMenu` → plain dropdown. Add `SubMenu` only where needed.
+
+## Controlled state
+
+```tsx
+const { open, setOpen, dropdownProps } = useDropdown1();
+
+<button onClick={() => setOpen(true)}>Open externally</button>
+<Dropdown1 {...dropdownProps} trigger={<span>Actions</span>}>
+  <Dropdown1.Item onClick={...}>Edit</Dropdown1.Item>
+</Dropdown1>
+```
+
+## Styling — coordinated colors
+
+Every layer uses **bg + text + hover** pairs from `dropdown1Styles` (Velocis tokens by default). Override any layer via the `styles` prop — `subMenuContent` inherits `content` when omitted.
+
+```tsx
+import { Dropdown1, dropdown1Styles } from 'velocis/dropdown1';
+
+// defaults — bg/text always matched
+<Dropdown1 trigger={<span>Actions</span>}>...</Dropdown1>
+
+// custom theme (dark panel example)
+<Dropdown1
+  trigger={<span>Actions</span>}
+  styles={{
+    trigger: 'bg-slate-900 text-white ring-slate-700 hover:bg-slate-800',
+    triggerIcon: 'text-slate-400',
+    content: 'bg-slate-900 text-white border-slate-700 shadow-xl ring-1 ring-slate-700/50',
+    item: 'text-slate-100 hover:bg-slate-800 hover:text-white',
+    subMenuTrigger: 'text-slate-100 hover:bg-slate-800 hover:text-white',
+    subMenuIcon: 'text-slate-400',
+  }}
+>
+  ...
+</Dropdown1>
+
+// tweak one layer only — rest stay default
+<Dropdown1 styles={{ content: dropdown1Styles.content, item: 'text-red-600 hover:bg-red-50' }}>
+  ...
+</Dropdown1>
+```
+
+| Style key | Default tokens | Applies to |
+|-----------|----------------|------------|
+| `trigger` | `bg-velocis-background text-velocis-foreground …` | Trigger button |
+| `triggerIcon` | `text-velocis-muted` | Trigger chevron |
+| `content` | `bg-velocis-background text-velocis-foreground …` | Main menu panel |
+| `item` | `text-velocis-foreground hover:bg-velocis-border/40` | `Dropdown1.Item` |
+| `subMenuTrigger` | same as `item` | Sub-menu row |
+| `subMenuContent` | inherits `content` | Sub-menu panel |
+| `subMenuIcon` | `text-velocis-muted` | Sub-menu chevron |
+
+Export `dropdown1Styles` and `resolveDropdown1Styles` for app-wide presets.
+
+## Props — `Dropdown1`
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `trigger` | required | Trigger label/content |
+| `children` | required | `Dropdown1.Item` and/or `Dropdown1.SubMenu` |
+| `open` / `defaultOpen` / `onOpenChange` | uncontrolled | Controlled open state |
+| `styles` | `dropdown1Styles` | Coordinated bg/text/hover per layer |
+| `triggerClassName` / `contentClassName` | — | Extra CSS classes |
+| `contentWidth` | `w-56` | Tailwind width class for menu panel |
+| `maxHeight` | — | Scrollable content max height |
+| `fullWidth` | `false` | Match trigger width to container |
+| `disabled` | `false` | Disable trigger |
+| `contentZIndex` | `--velocis-z-dropdown` | Raise z-index inside dialogs |
+| `closeOnScroll` | `true` | Close when scrolling outside menu |
+| `testId` / `contentTestId` | — | Test IDs |
+
+## Props — `Dropdown1.Item`
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `onClick` | — | Click handler |
+| `closeOnSelect` | `true` | Close menu after click |
+| `styles` | root `styles.item` | Override item colors |
+| `className` / `testId` | — | Extra CSS / test id |
+
+## Props — `Dropdown1.SubMenu`
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `trigger` | required | Sub-menu label |
+| `children` | required | Nested `Dropdown1.Item` elements |
+| `contentWidth` | `w-48` | Sub-menu panel width |
+| `styles` | root sub-menu styles | Override sub-menu colors |
+| `className` | — | Extra CSS on sub-menu panel |
+
+## RTL / LTR
+
+Dropdown1 respects `DirectionProvider` from `velocis/theme`. Sub-menus open toward inline-end (right in LTR, left in RTL) using logical CSS properties.
+
+## Accessibility
+
+- Trigger: `type="button"`, `aria-expanded`, `aria-haspopup="menu"`
+- Content: `role="menu"`, items: `role="menuitem"`
+- Escape closes the menu; click outside closes the menu
+
+## vs Dialog1 popover
+
+| | Dropdown1 | Dialog1 popover |
+|--|-----------|-----------------|
+| Use case | Action menus | Arbitrary panel content |
+| API | Item + SubMenu | Dialog compound layout |
+| Sub-menu | Built-in hover nested | Manual composition |

package/docs/feedback.md

@@ -0,0 +1,90 @@
+# Feedback (`velocis/feedback`)
+
+Loading, empty, and error states plus overlays and notifications.
+
+## Import
+
+```tsx
+import {
+  EmptyState,
+  LoadingState,
+  ErrorFallback,
+  SkeletonBase,
+  VelocisErrorBoundary,
+  Modal,
+  Alert,
+  ToastProvider,
+  useToast,
+  Tooltip,
+  Spinner,
+  Progress,
+  Badge,
+  Drawer,
+  Popover,
+  Chip,
+} from 'velocis/feedback';
+```
+
+## State components
+
+| Component | Use when |
+|-----------|----------|
+| `LoadingState` | Data is fetching |
+| `EmptyState` | No results / first-use |
+| `ErrorFallback` | Request or render failed |
+| `SkeletonBase` | Inline content placeholder |
+| `VelocisErrorBoundary` | Catch React render errors |
+| `Spinner` | Small inline spinner |
+| `Progress` | Determinate progress bar |
+
+### Examples
+
+```tsx
+if (status === 'loading') return <LoadingState message="Loading users…" />;
+if (status === 'error') return <ErrorFallback error={error} onRetry={refetch} />;
+if (!data.length) return <EmptyState title="No users" description="Add your first user." />;
+```
+
+## Overlays
+
+| Component | Use when |
+|-----------|----------|
+| `Modal` | Focused dialog / confirmation |
+| `Drawer` | Side panel |
+| `Popover` | Anchored floating content |
+| `Tooltip` | Hover hint on control |
+
+## Notifications
+
+Wrap app (or section) with `ToastProvider`, then call `useToast()`:
+
+```tsx
+import { ToastProvider, useToast } from 'velocis/feedback';
+
+function App() {
+  return (
+    <ToastProvider>
+      <MyPage />
+    </ToastProvider>
+  );
+}
+
+function MyPage() {
+  const toast = useToast();
+  return <button onClick={() => toast.success('Saved!')}>Save</button>;
+}
+```
+
+## Display components
+
+| Component | Use when |
+|-----------|----------|
+| `Alert` | Inline banner (info, warning, error) |
+| `Badge` | Status label on element |
+| `Chip` | Removable tag / filter chip |
+
+## When to use
+
+- Pair `LoadingState` / `EmptyState` / `ErrorFallback` with async tables and lists.
+- Use `Modal` for forms; `Drawer` for filters or detail panels.
+- Use `ToastProvider` once near the root for global toasts.

package/docs/forms.md

@@ -0,0 +1,78 @@
+# Forms (`velocis/forms`)
+
+Form layout and field components built on `react-hook-form`.
+
+## Import
+
+```tsx
+import {
+  FormRoot,
+  FormField,
+  FormSelect,
+  FormCheckbox,
+  FormTextarea,
+  FormSwitch,
+  FormDatePicker,
+  FormDateRangePicker,
+} from 'velocis/forms';
+```
+
+## Basic usage
+
+```tsx
+'use client';
+import { FormRoot, FormField, FormSelect } from 'velocis/forms';
+
+<FormRoot
+  defaultValues={{ name: '', role: '' }}
+  onSubmitData={(data) => console.log(data)}
+>
+  <FormField name="name" label="Name" placeholder="Your name" />
+  <FormSelect
+    name="role"
+    label="Role"
+    options={[
+      { value: 'admin', label: 'Admin' },
+      { value: 'user', label: 'User' },
+    ]}
+  />
+  <button type="submit">Submit</button>
+</FormRoot>
+```
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `FormRoot` | Form wrapper + `react-hook-form` provider |
+| `FormField` | Text input with label and validation message |
+| `FormSelect` | Dropdown select |
+| `FormCheckbox` | Checkbox |
+| `FormTextarea` | Multi-line text |
+| `FormSwitch` | Toggle switch |
+| `FormDatePicker` | Single date picker |
+| `FormDateRangePicker` | Start/end date range |
+
+## FormRoot props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onSubmitData` | `(data: Record<string, string>) => void` | Called on valid submit |
+| `defaultValues` | `Record<string, string>` | Initial field values |
+| `children` | `ReactNode` | Field components |
+| `className` | `string` | Form element class |
+
+## FormField props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `name` | `string` | required |
+| `label` | `string` | required |
+| `type` | `string` | `'text'` |
+| `placeholder` | `string` | — |
+
+## When to use
+
+- Use `FormRoot` as the single parent for all Velocis form fields.
+- Field `name` must match keys in `defaultValues` and `onSubmitData`.
+- For hero signup, see `HeroWithForm` in [hero.md](./hero.md).

package/docs/hero.md

@@ -0,0 +1,84 @@
+# Hero (`velocis/hero`)
+
+Landing-page hero section variants.
+
+## Import
+
+```tsx
+// All variants
+import {
+  HeroCentered,
+  HeroSplitImage,
+  HeroVideoBackground,
+  HeroGradientAnimated,
+  HeroWithForm,
+  HeroMinimalText,
+  HeroCarousel,
+  HeroParallax,
+  HeroStatsShowcase,
+  HeroAppDownload,
+  HeroPricingTeaser,
+  Hero3DTilt,
+  HeroTestimonial,
+  HeroNewsletter,
+  HeroComparison,
+  HeroBase,
+} from 'velocis/hero';
+
+// Tree-shaken single variant
+import { HeroCentered } from 'velocis/hero/centered';
+```
+
+## Shared props (`HeroVariantProps`)
+
+Most heroes accept:
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `title` | `string` | yes | Main heading |
+| `subtitle` | `string` | no | Supporting text |
+| `eyebrow` | `string` | no | Small label above title |
+| `actions` | `ReactNode` | no | CTA buttons |
+| `className` | `string` | no | Extra classes |
+
+## Variants
+
+| Component | Use when |
+|-----------|----------|
+| `HeroCentered` | Classic centered headline + CTA |
+| `HeroSplitImage` | Text on one side, image on the other |
+| `HeroVideoBackground` | Full-width video behind text |
+| `HeroGradientAnimated` | Animated gradient background |
+| `HeroWithForm` | Hero with embedded signup form |
+| `HeroMinimalText` | Typography-only, minimal layout |
+| `HeroCarousel` | Rotating slides |
+| `HeroParallax` | Parallax scroll effect |
+| `HeroStatsShowcase` | Highlight metrics / numbers |
+| `HeroAppDownload` | App store download CTAs |
+| `HeroPricingTeaser` | Pricing preview |
+| `Hero3DTilt` | 3D tilt interaction on media |
+| `HeroTestimonial` | Customer quote highlight |
+| `HeroNewsletter` | Email capture |
+| `HeroComparison` | Before/after or plan comparison |
+
+## Example
+
+```tsx
+import { HeroCentered } from 'velocis/hero/centered';
+
+<HeroCentered
+  eyebrow="New"
+  title="Build faster with Velocis"
+  subtitle="RTL-aware React components"
+  actions={<button>Get started</button>}
+/>
+```
+
+## Low-level building blocks
+
+`HeroBase`, `HeroContentProps`, `HeroMediaProps`, `HeroTextProps`, `HeroActionsProps` — for custom hero layouts.
+
+## When to use
+
+- Top-of-page marketing sections only.
+- Pick one variant per page section; prefer `velocis/hero/centered` import when using a single variant.

package/docs/list.md

@@ -0,0 +1,73 @@
+# List (`velocis/list`)
+
+List view variants for displaying collections.
+
+## Import
+
+```tsx
+import {
+  ListView,
+  SimpleList,
+  AvatarList,
+  GroupedList,
+  VirtualizedInfiniteList,
+  ReorderableList,
+  GridList,
+  TimelineList,
+  MasonryList,
+  KanbanList,
+} from 'velocis/list';
+```
+
+## Compound API (`ListView`)
+
+`ListView` defaults to `SimpleList`:
+
+| Property | Component | Use when |
+|----------|-----------|----------|
+| `ListView` / `ListView.Simple` | `SimpleList` | Basic text list |
+| `ListView.Avatar` | `AvatarList` | List with user avatars |
+| `ListView.Grouped` | `GroupedList` | Sections with headers |
+| `ListView.VirtualizedInfinite` | `VirtualizedInfiniteList` | Infinite scroll, large lists |
+| `ListView.Reorderable` | `ReorderableList` | Drag-to-reorder |
+| `ListView.Grid` | `GridList` | Grid layout of items |
+| `ListView.Timeline` | `TimelineList` | Chronological events |
+| `ListView.Masonry` | `MasonryList` | Pinterest-style masonry |
+| `ListView.Kanban` | `KanbanList` | Kanban board columns |
+
+## Basic example
+
+```tsx
+'use client';
+import { ListView } from 'velocis/list';
+
+const items = [
+  { id: '1', title: 'Item one', description: 'Details' },
+  { id: '2', title: 'Item two' },
+];
+
+<ListView items={items} />
+```
+
+## Types
+
+| Type | Package |
+|------|---------|
+| `ListItem`, `ListViewProps` | SimpleList |
+| `GridListItem`, `GridListProps` | GridList |
+| `TimelineItem`, `TimelineListProps` | TimelineList |
+| `MasonryListItem`, `MasonryListProps` | MasonryList |
+| `KanbanColumn`, `KanbanListProps` | KanbanList |
+
+## When to use
+
+| Scenario | Component |
+|----------|-----------|
+| Settings menu, notifications | `SimpleList` |
+| Team members | `AvatarList` |
+| Grouped contacts | `GroupedList` |
+| Feed with load more | `VirtualizedInfiniteList` |
+| Task priority reorder | `ReorderableList` |
+| Product gallery | `GridList` or `MasonryList` |
+| Activity log | `TimelineList` |
+| Project board | `KanbanList` |

package/docs/navigation.md

@@ -0,0 +1,102 @@
+# Navigation (`velocis/navigation`)
+
+Navigation, layout, and wayfinding components.
+
+## Import
+
+```tsx
+import {
+  Navigation,
+  Breadcrumb,
+  Pagination,
+  Tabs,
+  Accordion,
+  Stepper,
+  SearchInput,
+  FilterChips,
+  Navbar,
+  Sidebar,
+} from 'velocis/navigation';
+```
+
+## Namespace object
+
+`Navigation` groups all components:
+
+```tsx
+import { Navigation } from 'velocis/navigation';
+
+<Navigation.Tabs items={tabs} />
+<Navigation.Navbar items={navItems} />
+```
+
+Equivalent to importing each component directly.
+
+## Components
+
+| Component | Use when |
+|-----------|----------|
+| `Breadcrumb` | Page hierarchy trail |
+| `Pagination` | Page number navigation |
+| `Tabs` | Switch between views |
+| `Accordion` | Collapsible sections |
+| `Stepper` | Multi-step wizard progress |
+| `SearchInput` | Search field with icon |
+| `FilterChips` | Active filter tags |
+| `Navbar` | Top navigation bar |
+| `Sidebar` | Side navigation panel |
+
+## Examples
+
+### Tabs
+
+```tsx
+import { Tabs } from 'velocis/navigation';
+
+<Tabs
+  items={[
+    { id: 'overview', label: 'Overview', content: <Overview /> },
+    { id: 'settings', label: 'Settings', content: <Settings /> },
+  ]}
+/>
+```
+
+### Breadcrumb
+
+```tsx
+import { Breadcrumb } from 'velocis/navigation';
+
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Products', href: '/products' },
+    { label: 'Detail' },
+  ]}
+/>
+```
+
+### Navbar + Sidebar
+
+Use `Navbar` for horizontal top links and `Sidebar` for vertical app shell navigation.
+
+## Types
+
+| Type | Used by |
+|------|---------|
+| `BreadcrumbItem` | `Breadcrumb` |
+| `TabItem` | `Tabs` |
+| `AccordionItem` | `Accordion` |
+| `StepperStep` | `Stepper` |
+| `FilterChip` | `FilterChips` |
+| `NavbarItem` | `Navbar` |
+| `SidebarItem` | `Sidebar` |
+
+## When to use
+
+| Scenario | Component |
+|----------|-----------|
+| App shell | `Navbar` + `Sidebar` |
+| Settings sections | `Tabs` or `Accordion` |
+| Checkout flow | `Stepper` |
+| Data table filters | `SearchInput` + `FilterChips` |
+| Long result sets | `Pagination` (or `Table.Paginated`) |

package/docs/table.md

@@ -0,0 +1,111 @@
+# Table (`velocis/table`)
+
+Data tables with sorting, pagination, virtualization, and utilities.
+
+## Import
+
+```tsx
+import {
+  Table,
+  DataTable,
+  PaginatedTable,
+  ExpandableRowTable,
+  EditableTable,
+  VirtualizedTable,
+  TreeTable,
+  TableColumn,
+  useTableEngine,
+  useTableUrlSync,
+  useTablePersistence,
+} from 'velocis/table';
+```
+
+## Compound API (`Table`)
+
+`Table` defaults to `DataTable` and exposes variants as static properties:
+
+| Property | Component | Use when |
+|----------|-----------|----------|
+| `Table` / `Table.Data` | `DataTable` | Static in-memory data |
+| `Table.Paginated` | `PaginatedTable` | Server-side / async pagination |
+| `Table.Expandable` | `ExpandableRowTable` | Rows expand to show detail |
+| `Table.Editable` | `EditableTable` | Inline cell editing |
+| `Table.Virtualized` | `VirtualizedTable` | Large datasets (virtual scroll) |
+| `Table.Tree` | `TreeTable` | Hierarchical rows |
+| `Table.Column` | `TableColumn` | Column helper (PaginatedTable) |
+| `Table.Footer` | `TableFooter` | Custom table footer |
+| `Table.Export` | `TableExport` | Export data (CSV, etc.) |
+| `Table.ColumnVisibility` | `TableColumnVisibility` | Show/hide columns |
+| `Table.Aggregation` | `TableAggregation` | Sum/avg/count footer rows |
+| `Table.DetailPanel` | `TableDetailPanel` | Side detail panel |
+| `Table.Import` | `TableImport` | Import data from file |
+
+## Column definition
+
+```tsx
+const columns = [
+  { id: 'name', header: 'Name', accessor: 'name', sortable: true },
+  { id: 'email', header: 'Email', accessor: 'email' },
+  { id: 'role', header: 'Role', accessor: (row) => row.role },
+];
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique column id |
+| `header` | `string` | Column header label |
+| `accessor` | `keyof T \| (row) => ReactNode` | Cell value |
+| `sortable` | `boolean` | Enable sorting |
+| `width` | `string` | CSS width |
+
+## Basic example
+
+```tsx
+'use client';
+import { Table } from 'velocis/table';
+
+const data = [{ name: 'Alice', email: 'a@example.com', role: 'Admin' }];
+
+<Table data={data} columns={columns} />
+```
+
+## Paginated (async data)
+
+```tsx
+import { Table } from 'velocis/table';
+
+<Table.Paginated
+  dataSource={myDataSource}
+  columns={columns}
+/>
+```
+
+Requires a `DataSource<T>` from `@velocis/core` / `velocis`.
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useTableEngine` | Sort, filter, pagination, selection, expansion state |
+| `useTableUrlSync` | Sync table state to URL query params |
+| `useTablePersistence` | Persist column/state to localStorage |
+
+## Table props (shared)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `T[]` | Row data (static tables) |
+| `columns` | `ColumnDef<T>[]` | Column config |
+| `isLoading` | `boolean` | Loading state |
+| `getRowId` | `(row) => string \| number` | Stable row id |
+| `className` | `string` | Wrapper class |
+
+## When to use
+
+| Scenario | Component |
+|----------|-----------|
+| Small static list | `Table` / `DataTable` |
+| API-backed pages | `Table.Paginated` |
+| 1000+ rows | `Table.Virtualized` |
+| Nested categories | `Table.Tree` |
+| Master-detail | `Table.Expandable` + `Table.DetailPanel` |