velocis 1.2.0 → 1.3.0

package/docs/dropdown1.md

@@ -58,7 +58,7 @@ const { open, setOpen, dropdownProps } = useDropdown1();
 
 ## 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.
+Every layer uses **bg + text + hover** pairs from `dropdown1Styles` (Velocis tokens by default). Override any layer via the `styles` prop. `subMenuContent` has its own default and does **not** inherit `content` unless you set both to the same classes.
 
 ```tsx
 import { Dropdown1, dropdown1Styles } from 'velocis/dropdown1';
@@ -75,6 +75,7 @@ import { Dropdown1, dropdown1Styles } from 'velocis/dropdown1';
     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',
+    subMenuContent: 'bg-indigo-950 text-indigo-100 border-indigo-800 shadow-xl',
     subMenuIcon: 'text-slate-400',
   }}
 >
@@ -94,11 +95,91 @@ import { Dropdown1, dropdown1Styles } from 'velocis/dropdown1';
 | `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 |
+| `subMenuContent` | independent panel default | Sub-menu panel |
 | `subMenuIcon` | `text-velocis-muted` | Sub-menu chevron |
 
 Export `dropdown1Styles` and `resolveDropdown1Styles` for app-wide presets.
 
+## SubMenu placement
+
+Control where the sub-menu panel opens relative to the **main menu panel** with the `placement` prop on `Dropdown1.SubMenu`.
+
+```
+  left                          right (auto in LTR)
+┌─────────┐                 ┌─────────┐
+│ SubMenu │◄── gap ──►      │  Main   │── gap ──► ┌─────────┐
+└─────────┘                 │  panel  │           │ SubMenu │
+                            └─────────┘           └─────────┘
+
+  center
+       ┌─────────┐
+       │  Main   │
+       │  panel  │
+       └────┬────┘
+            ▼
+       ┌─────────┐
+       │ SubMenu │  (horizontally centered below panel)
+       └─────────┘
+```
+
+| `placement` | Position |
+|-------------|----------|
+| `'auto'` (default) | **RTL** → left of main panel — **LTR** → right of main panel |
+| `'left'` | Always to the physical left of the main panel edge |
+| `'right'` | Always to the physical right of the main panel edge |
+| `'center'` | Below the main panel, horizontally centered |
+
+Vertical alignment for `left` / `right` / `auto`: aligned with the sub-menu trigger row (natural cascade). For `center`: `top = panel.bottom + gap`.
+
+```tsx
+// auto — follows DirectionProvider (RTL=left, LTR=right)
+<Dropdown1.SubMenu trigger="More">...</Dropdown1.SubMenu>
+
+// force physical sides
+<Dropdown1.SubMenu placement="left" trigger="More">...</Dropdown1.SubMenu>
+<Dropdown1.SubMenu placement="right" trigger="More">...</Dropdown1.SubMenu>
+
+// below main panel, centered
+<Dropdown1.SubMenu placement="center" trigger="More">...</Dropdown1.SubMenu>
+```
+
+## SubMenu background (independent from main panel)
+
+The sub-menu panel can use a **different background** than the main menu:
+
+| Method | Use when |
+|--------|----------|
+| `styles={{ subMenuContent: '…' }}` on root or `SubMenu` | Tailwind class override |
+| `surface={{ background, tokens }}` on `Dropdown1.SubMenu` | Velocis surface API (same as root `surface`) |
+| Root `styles.content` only | Main panel — does **not** change sub-menu unless you also set `subMenuContent` |
+
+```tsx
+// White main menu + dark sub-menu via styles
+<Dropdown1 trigger={<span>Menu</span>}>
+  <Dropdown1.Item>Item</Dropdown1.Item>
+  <Dropdown1.SubMenu
+    trigger="More"
+    styles={{
+      subMenuContent:
+        'bg-indigo-950 text-indigo-100 border border-indigo-800 shadow-xl',
+    }}
+  >
+    <Dropdown1.Item>Sub item</Dropdown1.Item>
+  </Dropdown1.SubMenu>
+</Dropdown1>
+
+// Or surface on SubMenu only
+<Dropdown1.SubMenu
+  trigger="More"
+  surface={{
+    background: '#1e1b4b',
+    tokens: { foreground: '#e0e7ff' },
+  }}
+>
+  ...
+</Dropdown1.SubMenu>
+```
+
 ## Props — `Dropdown1`
 
 | Prop | Default | Description |
@@ -131,13 +212,15 @@ Export `dropdown1Styles` and `resolveDropdown1Styles` for app-wide presets.
 |------|---------|-------------|
 | `trigger` | required | Sub-menu label |
 | `children` | required | Nested `Dropdown1.Item` elements |
+| `placement` | `'auto'` | `'auto' \| 'left' \| 'right' \| 'center'` — see [SubMenu placement](#submenu-placement) |
 | `contentWidth` | `w-48` | Sub-menu panel width |
-| `styles` | root sub-menu styles | Override sub-menu colors |
+| `styles` | root sub-menu styles | Override `subMenuTrigger` / `subMenuContent` / `subMenuIcon` |
+| `surface` | — | Independent panel surface (background, tokens) |
 | `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.
+Dropdown1 respects `DirectionProvider` from `velocis/theme`. Main panel alignment follows direction. Sub-menu `placement="auto"` opens toward inline-start in RTL (left of panel) and inline-end in LTR (right of panel). Use `placement="left"` or `"right"` for fixed physical sides.
 
 ## Accessibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "velocis",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Extremely dynamic RTL/LTR React UI component library",
   "license": "MIT",
   "type": "module",
@@ -101,18 +101,18 @@
     }
   },
   "dependencies": {
-    "@velocis/card": "0.2.0",
     "@velocis/core": "0.1.0",
+    "@velocis/card": "0.2.0",
     "@velocis/forms": "0.1.0",
     "@velocis/feedback": "0.1.2",
     "@velocis/navigation": "0.1.2",
-    "@velocis/hero": "0.1.0",
     "@velocis/list": "0.1.2",
+    "@velocis/table": "0.1.2",
+    "@velocis/hero": "0.1.0",
     "@velocis/table2": "0.2.2",
+    "@velocis/dropdown1": "0.4.0",
     "@velocis/dialog1": "0.3.0",
-    "@velocis/theme": "0.2.0",
-    "@velocis/dropdown1": "0.3.0",
-    "@velocis/table": "0.1.2"
+    "@velocis/theme": "0.2.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",