velocis 1.0.1 → 1.1.1

package/AGENTS.md

@@ -0,0 +1,29 @@
+# AI / Agent reference
+
+When integrating Velocis in a consumer project, read these files (included in the published npm package under `node_modules/velocis/docs/`):
+
+1. **[docs/README.md](./docs/README.md)** — setup, import rules, component picker
+2. **Module docs** — `docs/theme.md`, `docs/card.md`, `docs/hero.md`, `docs/table.md`, `docs/table2.md`, `docs/dialog1.md`, `docs/dropdown1.md`, `docs/list.md`, `docs/feedback.md`, `docs/forms.md`, `docs/navigation.md`, `docs/core.md`
+
+## Rules
+
+- Always import `velocis/styles.css` in the root layout.
+- Wrap the app with `VelocisProvider` and `DirectionProvider` from `velocis/theme`.
+- Use subpath imports: `velocis/table`, `velocis/card`, etc.
+- Use `'use client'` for interactive components in Next.js App Router.
+- Pick the variant documented in each module's "When to use" section.
+
+## Quick picker
+
+| Task | Import |
+|------|--------|
+| Data grid | `Table` from `velocis/table` |
+| Custom UI table | `Table2` from `velocis/table2` |
+| Dialog / popup / anchored | `Dialog1` from `velocis/dialog1` |
+| Action menu | `Dropdown1` from `velocis/dropdown1` |
+| Card UI | `Card` from `velocis/card` |
+| Landing hero | `HeroCentered` from `velocis/hero/centered` |
+| Item list | `ListView` from `velocis/list` |
+| Loading state | `LoadingState` from `velocis/feedback` |
+| Form | `FormRoot`, `FormField` from `velocis/forms` |
+| Tabs / nav | `Tabs`, `Navbar` from `velocis/navigation` |

package/README.md

@@ -0,0 +1,33 @@
+# velocis
+
+Meta package — publishes all Velocis UI modules under subpath imports.
+
+## Consumer imports
+
+| Subpath | Module |
+|---------|--------|
+| `velocis` | Everything (core + all components) |
+| `velocis/theme` | Providers & tokens |
+| `velocis/card` | Card |
+| `velocis/hero` | Hero variants |
+| `velocis/hero/centered` | Single hero (tree-shaken) |
+| `velocis/table` | Tables |
+| `velocis/list` | Lists |
+| `velocis/feedback` | States & overlays |
+| `velocis/forms` | Forms |
+| `velocis/navigation` | Navigation |
+| `velocis/styles.css` | Pre-built CSS |
+| `velocis/tailwind-preset` | Tailwind preset |
+
+Full documentation: [docs/README.md](../../docs/README.md) · [AGENTS.md](../../AGENTS.md) (AI agent reference)
+
+## Quick start
+
+```tsx
+import 'velocis/styles.css';
+import { VelocisProvider, DirectionProvider } from 'velocis/theme';
+import { Card } from 'velocis/card';
+import { Table } from 'velocis/table';
+```
+
+Prefer subpath imports over `import { … } from 'velocis'` for smaller bundles.

package/dist/card.d.cts

@@ -1,4 +1,6 @@
 export * from '@velocis/card';
+import '@velocis/dialog1';
+import '@velocis/dropdown1';
 import '@velocis/feedback';
 import '@velocis/forms';
 import '@velocis/hero';
@@ -7,4 +9,5 @@ import '@velocis/theme';
 import '@velocis/table';
 import '@velocis/list';
 import '@velocis/navigation';
+import '@velocis/table2';
 import '@velocis/theme/tailwind-preset';

package/dist/card.d.ts

@@ -1,4 +1,6 @@
 export * from '@velocis/card';
+import '@velocis/dialog1';
+import '@velocis/dropdown1';
 import '@velocis/feedback';
 import '@velocis/forms';
 import '@velocis/hero';
@@ -7,4 +9,5 @@ import '@velocis/theme';
 import '@velocis/table';
 import '@velocis/list';
 import '@velocis/navigation';
+import '@velocis/table2';
 import '@velocis/theme/tailwind-preset';

package/dist/dialog1.cjs

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/dialog1.ts
+var dialog1_exports = {};
+module.exports = __toCommonJS(dialog1_exports);
+__reExport(dialog1_exports, require("@velocis/dialog1"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@velocis/dialog1")
+});

package/dist/dialog1.d.cts

@@ -0,0 +1 @@
+export * from '@velocis/dialog1';

package/dist/dialog1.d.ts

@@ -0,0 +1 @@
+export * from '@velocis/dialog1';

package/dist/dialog1.js

@@ -0,0 +1,2 @@
+// src/dialog1.ts
+export * from "@velocis/dialog1";

package/dist/dropdown1.cjs

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/dropdown1.ts
+var dropdown1_exports = {};
+module.exports = __toCommonJS(dropdown1_exports);
+__reExport(dropdown1_exports, require("@velocis/dropdown1"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@velocis/dropdown1")
+});

package/dist/dropdown1.d.cts

@@ -0,0 +1 @@
+export * from '@velocis/dropdown1';

package/dist/dropdown1.d.ts

@@ -0,0 +1 @@
+export * from '@velocis/dropdown1';

package/dist/dropdown1.js

@@ -0,0 +1,2 @@
+// src/dropdown1.ts
+export * from "@velocis/dropdown1";

package/dist/table2.cjs

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/table2.ts
+var table2_exports = {};
+module.exports = __toCommonJS(table2_exports);
+__reExport(table2_exports, require("@velocis/table2"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@velocis/table2")
+});

package/dist/table2.d.cts

@@ -0,0 +1 @@
+export * from '@velocis/table2';

package/dist/table2.d.ts

@@ -0,0 +1 @@
+export * from '@velocis/table2';

package/dist/table2.js

@@ -0,0 +1,2 @@
+// src/table2.ts
+export * from "@velocis/table2";

package/docs/README.md

@@ -0,0 +1,89 @@
+# Velocis Documentation
+
+Reference for developers and AI agents integrating the `velocis` React UI library.
+
+## Install
+
+```bash
+npm install velocis
+```
+
+## Required setup
+
+```tsx
+// app/layout.tsx
+import 'velocis/styles.css';
+import { VelocisProvider, DirectionProvider } from 'velocis/theme';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <VelocisProvider theme="system">
+          <DirectionProvider direction="ltr">{children}</DirectionProvider>
+        </VelocisProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Import rules
+
+| Context | Import from | Example |
+|---------|-------------|---------|
+| External app (npm) | `velocis/...` subpaths | `import { Table } from 'velocis/table'` |
+| Monorepo internal | `@velocis/...` packages | `import { Table } from '@velocis/table'` |
+| Everything at once | `velocis` | `import { Table, Card } from 'velocis'` |
+
+Prefer subpath imports (`velocis/table`, `velocis/card`, …) for smaller bundles.
+
+## Module index
+
+| Module | Import path | Doc |
+|--------|-------------|-----|
+| Theme & providers | `velocis/theme` | [theme.md](./theme.md) |
+| Card | `velocis/card` | [card.md](./card.md) |
+| Hero sections | `velocis/hero`, `velocis/hero/centered` | [hero.md](./hero.md) |
+| Tables | `velocis/table` | [table.md](./table.md) |
+| Custom tables | `velocis/table2` | [table2.md](./table2.md) |
+| Dialogs & popovers | `velocis/dialog1` | [dialog1.md](./dialog1.md) |
+| Action menus | `velocis/dropdown1` | [dropdown1.md](./dropdown1.md) |
+| Lists | `velocis/list` | [list.md](./list.md) |
+| Feedback & overlays | `velocis/feedback` | [feedback.md](./feedback.md) |
+| Forms | `velocis/forms` | [forms.md](./forms.md) |
+| Navigation | `velocis/navigation` | [navigation.md](./navigation.md) |
+| Primitives & hooks | `velocis` (core re-export) | [core.md](./core.md) |
+
+## Quick component picker
+
+| Need | Use |
+|------|-----|
+| Landing page header | `HeroCentered`, `HeroSplitImage`, … → [hero.md](./hero.md) |
+| Content container | `Card` → [card.md](./card.md) |
+| Data grid | `Table`, `Table.Paginated`, `Table.Tree` → [table.md](./table.md) |
+| Custom UI table | `Table2`, `useTable2Selection` → [table2.md](./table2.md) |
+| Item list | `ListView`, `ListView.Avatar`, `ListView.Kanban` → [list.md](./list.md) |
+| Loading / empty / error | `LoadingState`, `EmptyState`, `ErrorFallback` → [feedback.md](./feedback.md) |
+| Modal / toast / alert | `Modal`, `useToast`, `Alert` → [feedback.md](./feedback.md) |
+| Anchored dialog / popover | `Dialog1`, `useDialog1Anchor` → [dialog1.md](./dialog1.md) |
+| Action menu / nested menu | `Dropdown1` → [dropdown1.md](./dropdown1.md) |
+| Form with fields | `FormRoot`, `FormField`, `FormSelect` → [forms.md](./forms.md) |
+| Tabs / navbar / sidebar | `Tabs`, `Navbar`, `Sidebar` → [navigation.md](./navigation.md) |
+| RTL / dark mode | `VelocisProvider`, `DirectionProvider` → [theme.md](./theme.md) |
+
+## Styles
+
+```tsx
+import 'velocis/styles.css';           // pre-built CSS (recommended)
+// or Tailwind v4:
+import 'velocis/tailwind-v4.css';
+```
+
+## CSS / Tailwind preset
+
+```js
+// tailwind.config.js
+import velocisPreset from 'velocis/tailwind-preset';
+export default { presets: [velocisPreset] };
+```

package/docs/card.md

@@ -0,0 +1,77 @@
+# Card (`velocis/card`)
+
+Flexible card container with variants and compound subcomponents.
+
+## Import
+
+```tsx
+import { Card, CardSkeleton, cardVariants, CARD_DEFAULT_PROPS } from 'velocis/card';
+import type { CardProps, CardVariantProps } from 'velocis/card';
+```
+
+## Basic usage
+
+```tsx
+<Card variant="glass" size="lg" interactive="hoverLift">
+  <Card.Header title="Title" description="Subtitle" />
+  <Card.Body>Content here</Card.Body>
+  <Card.Footer>Actions</Card.Footer>
+</Card>
+```
+
+## Variants
+
+| `variant` | Description |
+|-----------|-------------|
+| `elevated` | Default, shadow + border |
+| `outline` | Border only, no shadow |
+| `glass` | Frosted glass / backdrop blur |
+| `gradient` | Subtle gradient background |
+| `minimal` | Transparent, no border |
+| `neumorphic` | Soft embossed look |
+| `borderedAccent` | Left accent border |
+
+## Sizes
+
+`sm` | `md` (default) | `lg` | `xl`
+
+## Interactive modes
+
+| `interactive` | Behavior |
+|---------------|----------|
+| `false` | Static (default) |
+| `hoverLift` | Lifts on hover |
+| `pressable` | Scale-down on press |
+
+## Compound subcomponents
+
+| Component | Purpose |
+|-----------|---------|
+| `Card.Header` | Title + description |
+| `Card.Media` | Image or media slot |
+| `Card.Body` | Main content |
+| `Card.Footer` | Footer actions |
+| `Card.Badge` | Corner badge |
+| `Card.Actions` | Action button row |
+| `Card.Collapse` | Expandable section |
+| `Card.Grid` | Card grid layout |
+| `Card.Selectable` | Selectable card state |
+| `Card.Skeleton` | Loading placeholder |
+
+## Props (root)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `variant` | see variants | Visual style |
+| `size` | `sm \| md \| lg \| xl` | Padding scale |
+| `interactive` | `false \| hoverLift \| pressable` | Hover/press behavior |
+| `isLoading` | `boolean` | Shows `CardSkeleton` |
+| `asChild` | `boolean` | Merge props onto child |
+| `renderHeader` | `() => ReactNode` | Custom header slot |
+| `renderFooter` | `() => ReactNode` | Custom footer slot |
+
+## When to use
+
+- Display grouped content, dashboards, product tiles.
+- Use `variant="glass"` for overlays on images.
+- Use `isLoading` while fetching card data.

package/docs/core.md

@@ -0,0 +1,75 @@
+# Core (via `velocis`)
+
+Primitives, hooks, and utilities. Re-exported from the main `velocis` package (source: `@velocis/core`).
+
+## Import
+
+```tsx
+// External apps
+import { Box, Flex, cn, useDirection, useAsyncData } from 'velocis';
+
+// Monorepo
+import { Box, Flex, cn } from '@velocis/core';
+```
+
+## Layout primitives
+
+| Component | Purpose |
+|-----------|---------|
+| `Box` | Generic container |
+| `Flex` | Flexbox layout |
+| `Grid` | CSS grid layout |
+| `Stack` | Vertical/horizontal stack |
+| `Container` | Max-width page container |
+| `Spacer` | Flexible space |
+| `Divider` | Horizontal/vertical rule |
+| `AspectRatio` | Fixed aspect ratio box |
+| `Text` | Typography wrapper |
+| `VisuallyHidden` | Screen-reader-only content |
+| `Icon` | Icon wrapper |
+| `Portal` | Render outside DOM hierarchy |
+| `Overlay` | Full-screen overlay |
+| `Avatar` | User avatar |
+| `SkipLink` | Accessibility skip link |
+| `Slot` | Merge props onto child element |
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useDirection` | Current `ltr` / `rtl` from context |
+| `useMergedClassNames` | Merge class name strings |
+| `useAsyncData` | Fetch paginated async data (`DataSource`) |
+| `useVirtualizer` | Virtual scroll calculations |
+| `useIdSafe` | SSR-safe unique ids |
+| `useReducedMotion` | Respect `prefers-reduced-motion` |
+| `useFocusTrap` | Trap focus in modal |
+| `useUndoRedo` | Undo/redo state stack |
+
+## Utilities
+
+| Export | Purpose |
+|--------|---------|
+| `cn` | Merge Tailwind classes |
+| `rtl` helpers | RTL-aware positioning |
+| `responsive` helpers | Breakpoint utilities |
+| `VelocisError` | Library error type |
+
+## Async data (for tables)
+
+```tsx
+import { useAsyncData } from 'velocis';
+
+const { data, status, error, refetch, total } = useAsyncData({
+  dataSource: mySource,
+  params: { page: 1, pageSize: 10 },
+});
+```
+
+Used internally by `PaginatedTable`. Status values: `'loading' | 'empty' | 'error' | 'success'`.
+
+## When to use
+
+- Build custom layouts not covered by Card, List, or Navigation.
+- Use `cn` everywhere you compose Tailwind classes with Velocis components.
+- Use `useAsyncData` when building custom data views with the same pattern as `Table.Paginated`.

package/docs/dialog1.md

@@ -0,0 +1,180 @@
+# Dialog1 (`velocis/dialog1`)
+
+Highly flexible dialogs: centered modal, popover anchored to a trigger, and side anchored panel — with full RTL/LTR support and CSS customization at every layer.
+
+Use **Dialog1** for anchored popups and custom dialog layouts. Use [`velocis/feedback`](./feedback.md) `Modal` for simple centered confirmations.
+
+## Import
+
+```tsx
+'use client';
+
+import {
+  Dialog1,
+  useDialog1,
+  useDialog1Anchor,
+  useAlertDialog,
+  dialog1Styles,
+} from 'velocis/dialog1';
+```
+
+## When to use
+
+| Scenario | Use |
+|----------|-----|
+| Centered popup / form | `variant="modal"` |
+| Menu / dropdown beside button | `variant="popover"` + `useDialog1Anchor` |
+| Side panel beside trigger | `variant="anchored"` |
+| Quick alert | `useAlertDialog` or `Dialog1.Alert` |
+| Simple confirmation | `Modal` from [`velocis/feedback`](./feedback.md) |
+
+## Variants
+
+| Variant | Behavior |
+|---------|----------|
+| `modal` | Centered overlay, body scroll lock, focus trap |
+| `popover` | Fixed panel below/near anchor, viewport clamping |
+| `anchored` | Full-height side panel beside anchor |
+
+## Quick setup — modal
+
+```tsx
+const { show, dialogProps } = useDialog1();
+
+<button onClick={show}>Open</button>
+<Dialog1 {...dialogProps}>
+  <Dialog1.Content>
+    <Dialog1.Header>
+      <Dialog1.Title>Title</Dialog1.Title>
+    </Dialog1.Header>
+    <p>Content here</p>
+    <Dialog1.Close onClose={() => dialogProps.onOpenChange(false)} />
+  </Dialog1.Content>
+</Dialog1>
+```
+
+## Quick setup — popover (anchored to button)
+
+```tsx
+const { open, setOpen, anchorRef, dialogProps } = useDialog1Anchor({
+  variant: 'popover',
+  placement: 'bottom-start',
+});
+
+<button ref={anchorRef} onClick={() => setOpen(true)}>Menu</button>
+<Dialog1 {...dialogProps} anchorRef={anchorRef}>
+  <Dialog1.Content className="p-4">
+    <p>Popover content</p>
+  </Dialog1.Content>
+</Dialog1>
+```
+
+## Quick setup — anchored side panel
+
+```tsx
+const { anchorRef, dialogProps, setOpen } = useDialog1Anchor({
+  variant: 'anchored',
+  anchoredWidthPx: 320,
+  anchoredTop: '20%',
+});
+
+<button ref={anchorRef} onClick={() => setOpen(true)}>Filters</button>
+<Dialog1 {...dialogProps} anchorRef={anchorRef}>
+  <Dialog1.Content>...</Dialog1.Content>
+</Dialog1>
+```
+
+## Alert dialog
+
+```tsx
+const { show, AlertDialog } = useAlertDialog({
+  title: 'تنبيه',
+  description: 'هل أنت متأكد؟',
+  confirmLabel: 'حسناً',
+  dir: 'rtl',
+});
+
+<button onClick={show}>Show alert</button>
+{AlertDialog}
+```
+
+## RTL / LTR
+
+- Default direction from `DirectionProvider` (`useDirection`)
+- Override per dialog: `dir="rtl"` or `dir="ltr"`
+- `placement` is **logical**: `bottom-start` = below + inline-start (right in RTL, left in LTR)
+- `Dialog1Close` positions on logical start side
+- Mixed content: set `dir` on subcomponents independently
+
+## CSS customization
+
+### Level 1 — root props
+
+```tsx
+<Dialog1
+  rootClassName="..."
+  backdropClassName="bg-black/50"
+  panelClassName="rounded-3xl shadow-xl"
+  panelStyle={{ zoom: 0.95 }}
+/>
+```
+
+### Level 2 — subcomponents
+
+Every subcomponent accepts `className` + native HTML attributes:
+
+```tsx
+<Dialog1.Header className="bg-velocis-background px-6" />
+<Dialog1.Title className="text-3xl" />
+<Dialog1.Footer className="justify-between" />
+```
+
+### Level 3 — presets
+
+```tsx
+import { dialog1Styles, cardPanelStyles } from 'velocis/dialog1';
+import { cn } from 'velocis';
+
+<Dialog1 panelClassName={cn(dialog1Styles.panel, cardPanelStyles.panel)} />
+```
+
+## Compound API
+
+| Property | Component |
+|----------|-----------|
+| `Dialog1` | Root |
+| `Dialog1.Content` | Scrollable body wrapper |
+| `Dialog1.Header` | Header slot |
+| `Dialog1.Title` | Title heading |
+| `Dialog1.Description` | Description text |
+| `Dialog1.Footer` | Footer actions |
+| `Dialog1.Close` | Close button (logical position) |
+| `Dialog1.Alert` | Pre-built alert modal |
+
+## Props reference (`Dialog1`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | — | Controlled open state |
+| `onOpenChange` | `(open) => void` | — | State callback |
+| `variant` | `modal \| popover \| anchored` | `modal` | Display mode |
+| `anchorRef` | `RefObject<HTMLElement>` | — | Trigger element |
+| `getAnchorElement` | `() => HTMLElement \| null` | — | Dynamic anchor resolver |
+| `placement` | `bottom-start \| bottom-end \| top-start \| top-end` | `bottom-start` | Popover placement |
+| `offset` | `number` | `8` | Gap from anchor (px) |
+| `maxWidth` | `string` | `max-w-4xl` | Tailwind max-width class |
+| `elevated` | `boolean` | `false` | Higher z-index layer |
+| `dir` | `rtl \| ltr` | from provider | Text direction |
+| `popoverMaxWidthPx` | `number` | `288` | Popover width cap |
+| `anchoredTop` | `string` | `30%` | Anchored panel top offset |
+| `anchoredWidthPx` | `number` | `300` | Anchored panel width |
+
+## vs `velocis/feedback`
+
+| | `Modal` / `Popover` | `Dialog1` |
+|--|---------------------|-----------|
+| Modes | Centered / basic popover | modal + popover + anchored |
+| Anchor | Internal trigger only | `anchorRef` + `getAnchorElement` |
+| Positioning | Static | Placement + clamp + scroll sync |
+| CSS | Single `className` | Slots on every layer |
+| Setup | Manual props | `useDialog1`, `useDialog1Anchor` |