@olympusoss/canvas 4.0.0 → 5.0.0

package/src/organisms/overlays/overlays.shared.tsx

@@ -0,0 +1,175 @@
+import { useState } from "react";
+import { View, Text, Pressable, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Button } from "../../atoms/button/button.js";
+import { Icon } from "../../atoms/icon/icon.js";
+import * as s from "./overlays.styles.js";
+import { type Placement, type OverlaySkin } from "./overlays.styles.js";
+
+// Shared Overlay shell. The structure (the optional trigger plus a CONTAINED dim
+// backdrop holding the surface positioned per placement), the public
+// boolean-prop API, the placement precedence, the controlled/uncontrolled open
+// state, the trigger/Done handlers, and the footer action all live here once. A
+// platform file supplies only its skin (the surface shape/fill/sizing and the
+// grabber/drag handle) and calls createOverlay.
+//
+// Overlay: a dim backdrop with a surface anchored to a side or the center,
+// rendered INLINE for the docs preview. Rather than a full-screen portal/Modal,
+// this is a CONTAINED backdrop View (a rounded, clipped scrim with explicit
+// presence in the preview) that holds the overlay surface positioned inside it:
+// a right-side drawer, a bottom sheet, or a centered modal/panel.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Dialog/Button). Placement axis (pick one):
+//
+// - `drawer`: a panel anchored to the right edge, full height (the default).
+// - `sheet`: a panel anchored to the bottom edge, spanning the width.
+// - `modal`: a centered card floating over the backdrop.
+
+export interface OverlayProps {
+  // Content (strings).
+  title?: string;
+  description?: string;
+  // Trigger button label. When set, the overlay renders the button and opens
+  // itself on press (uncontrolled). Omit when you drive `open` yourself.
+  trigger?: string;
+  // Controlled open state. Omit for uncontrolled (the trigger opens it).
+  open?: boolean;
+  // Fired when the open state changes (trigger press, done).
+  onOpenChange?: (open: boolean) => void;
+  // Placement (pick one; first match wins, default is the right-side drawer).
+  drawer?: boolean;
+  sheet?: boolean;
+  modal?: boolean;
+  // Footer action label.
+  doneLabel?: string;
+  // Action handler.
+  onDone?: () => void;
+  /** Escape hatch for layout/positioning composition on the overlay surface. */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Placement precedence when more than one is passed: first match wins.
+function placementOf(p: OverlayProps): Placement {
+  if (p.drawer) return "drawer";
+  if (p.sheet) return "sheet";
+  if (p.modal) return "modal";
+  return "drawer";
+}
+
+/** Build an Overlay component from a platform skin. */
+export function createOverlay(skin: OverlaySkin) {
+  return function Overlay(props: OverlayProps) {
+    const { title, description, trigger, open: openProp, onOpenChange, doneLabel = "Done", onDone, style } = props;
+    const { tokens } = useTheme();
+
+    // Uncontrolled by default: the trigger opens the overlay and Done closes it;
+    // a controlled `open` prop overrides this.
+    const [internalOpen, setInternalOpen] = useState(false);
+    const open = openProp ?? internalOpen;
+    const setOpen = (next: boolean) => {
+      if (openProp === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+
+    const placement = placementOf(props);
+
+    // The grabber/drag handle renders on the `sheet` placement only, and only
+    // when the platform skin draws one (iOS/Android, not the web).
+    const showHandle = placement === "sheet" && skin.handle != null;
+
+    // The iOS 27 sheet header toolbar (leading circular close, centered title,
+    // trailing circular action) renders on the `sheet` placement only, and only
+    // when the platform skin supplies the header pieces (iOS, not web/Android).
+    // Web/Android leave `sheetHeader` undefined and keep the title/description/
+    // footer stack below unchanged.
+    const showSheetHeader =
+      placement === "sheet" && skin.sheetHeader != null && skin.headerButton != null;
+
+    const close = () => setOpen(false);
+    const done = () => {
+      onDone?.();
+      setOpen(false);
+    };
+
+    // Optional trigger button plus the overlay. The overlay is a contained dim
+    // backdrop: a rounded, clipped scrim with explicit presence in the preview
+    // (minHeight) so the surface reads as an overlay within the area.
+    return (
+      <View style={s.root}>
+        {trigger != null ? (
+          <View style={s.triggerWrap}>
+            <Button outline small onPress={() => setOpen(true)}>
+              {trigger}
+            </Button>
+          </View>
+        ) : null}
+        {open ? (
+          <View
+            style={[
+              trigger != null ? s.backdropWithTrigger : null,
+              s.backdrop(),
+              s.backdropPlacement[placement],
+              { minHeight: 280 },
+            ]}
+          >
+            <View style={[skin.surface(tokens, placement), style]}>
+              {showHandle ? (
+                <View style={s.handleWrap}>
+                  <View style={skin.handle!(tokens)} />
+                </View>
+              ) : null}
+              {showSheetHeader ? (
+                // iOS 27 sheet header toolbar: leading circular close (X), centered
+                // title, trailing circular accent action. The title centers in the
+                // row; the side controls are equal-width slots so it stays centered.
+                <View style={skin.sheetHeader}>
+                  <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel="Close"
+                    onPress={close}
+                    style={({ pressed }) => [
+                      skin.headerButton!(tokens),
+                      pressed ? { opacity: 0.8 } : null,
+                    ]}
+                  >
+                    <Icon x muted size={20} />
+                  </Pressable>
+                  <View style={s.sheetHeaderTitleWrap}>
+                    {title != null ? (
+                      <Text numberOfLines={1} style={(skin.headerTitle ?? skin.title)(tokens)}>
+                        {title}
+                      </Text>
+                    ) : null}
+                  </View>
+                  <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={doneLabel}
+                    onPress={done}
+                    style={({ pressed }) => [
+                      (skin.headerButtonAccent ?? skin.headerButton)!(tokens),
+                      pressed ? { opacity: 0.8 } : null,
+                    ]}
+                  >
+                    <Icon upload primaryForeground size={20} />
+                  </Pressable>
+                </View>
+              ) : (
+                <>
+                  {title != null ? <Text style={skin.title(tokens)}>{title}</Text> : null}
+                  {description != null ? (
+                    <Text style={skin.description(tokens)}>{description}</Text>
+                  ) : null}
+                  <View style={skin.footer}>
+                    <Button primary small onPress={done}>
+                      {doneLabel}
+                    </Button>
+                  </View>
+                </>
+              )}
+            </View>
+          </View>
+        ) : null}
+      </View>
+    );
+  };
+}

package/src/organisms/overlays/overlays.styles.ts

@@ -0,0 +1,309 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, shadow, alpha } from "../../style/index.js";
+
+// Co-located Overlay skins, one per platform, all driven by the brand tokens
+// (passed in from useTheme so they follow light/dark and read as glass when
+// tokens.popover is swapped translucent at the theming level). The BRAND
+// survives on every platform (the indigo `primary` Done action stays the same);
+// only the native SHAPE, sizing, surface treatment, and the grabber/handle change
+// per OS:
+//   iOS (iOS 27 / Liquid Glass sheet): a sheet with the TOP corners rounded ~38
+//     presenting from the bottom (flat bottom), a small grabber handle (a ~36x5
+//     rounded `muted-foreground` pill) centered at the top, and an iOS 27 header
+//     toolbar directly below it: a leading CIRCULAR tinted button holding the close
+//     (X) glyph, a centered title, and a trailing CIRCULAR action button (a filled
+//     `primary` accent circle holding the action glyph) — both are ~40pt circles,
+//     not bare icons. The centered `modal` becomes a rounded form-sheet card
+//     (~13 radius). Press feedback on the surface is none (the surface itself is
+//     not pressable); the circular header buttons keep the Button's iOS press =
+//     opacity dim.
+//   Android (Material 3 bottom sheet): the `sheet` has its TOP corners rounded 28
+//     with a centered drag handle (~32x4 rounded `muted-foreground` pill), the
+//     `popover` surface, and M3 elevation; the `drawer` and `modal` keep the M3
+//     low-radius/elevated treatment.
+//   Web: the established Canvas look (the current overlay, lifted verbatim) — the
+//     contained dim scrim with the drawer (right, full height, border-l), sheet
+//     (bottom, rounded-t-lg, border-t), and modal (centered card, rounded-lg
+//     border) surfaces, each `popover` filled with a border and shadow-xl.
+
+export type Placement = "drawer" | "sheet" | "modal";
+
+// The contract a platform skin fulfills. The shell renders the contained dim
+// backdrop, the surface positioned inside it per placement, an optional top
+// grabber/drag handle (sheet only), the title, the description, and the footer
+// action row; the skin maps the active platform's shape/fill/sizing onto each
+// piece. `backdrop` and the contents type styles read the tokens so light/dark/
+// glass keep working.
+export interface OverlaySkin {
+  /** The overlay surface per placement: shape, fill, border, padding, shadow. */
+  surface: (t: ColorTokens, placement: Placement) => ViewStyle;
+  /** The top grabber/drag handle rendered on the `sheet` placement only. Null on
+   *  platforms that do not draw one (web). The shell centers it; this is the pill. */
+  handle: ((t: ColorTokens) => ViewStyle) | null;
+  /** The title type/color. */
+  title: (t: ColorTokens) => TextStyle;
+  /** The description type/color. */
+  description: (t: ColorTokens) => TextStyle;
+  /** The footer action row layout. */
+  footer: ViewStyle;
+
+  // --- iOS 27 sheet header (optional; iOS skin only) ------------------------
+  // When a skin supplies `sheetHeader`, the shell renders an iOS 27 sheet header
+  // toolbar on the `sheet` placement instead of the title/description/footer
+  // stack: a leading CIRCULAR close (X) button, a centered title, and a trailing
+  // CIRCULAR action button. Web/Android leave these undefined and keep the plain
+  // title/description/footer layout byte-for-byte.
+
+  /** The header toolbar row (3-column: leading circle, centered title, trailing
+   *  circle). Present only on platforms that draw the iOS 27 sheet header. */
+  sheetHeader?: ViewStyle;
+  /** The circular tinted header button (a ~40pt `muted` circle behind a glyph). */
+  headerButton?: (t: ColorTokens) => ViewStyle;
+  /** The filled-accent trailing header button (a ~40pt `primary` circle). */
+  headerButtonAccent?: (t: ColorTokens) => ViewStyle;
+  /** The centered header title type/color (the iOS 27 sheet navigation title). */
+  headerTitle?: (t: ColorTokens) => TextStyle;
+}
+
+// --- outer wrapper + trigger (identical across platforms) -------------------
+
+// w-full: the overlay occupies the full width of its slot.
+export const root: ViewStyle = { width: "100%" };
+
+// self-start: the trigger button hugs the leading edge.
+export const triggerWrap: ViewStyle = { alignSelf: "flex-start" };
+
+// --- backdrop (identical across platforms) ----------------------------------
+
+// The contained dim scrim: relative w-full overflow-hidden rounded-lg bg-black/50.
+// (mt-3 is applied conditionally by the shell when a trigger is present.)
+export function backdrop(): ViewStyle {
+  return {
+    position: "relative",
+    width: "100%",
+    overflow: "hidden",
+    borderRadius: 8,
+    backgroundColor: alpha("#000000", 0.5),
+  };
+}
+
+// mt-3: gap below the trigger button, applied only when a trigger is rendered.
+export const backdropWithTrigger: ViewStyle = { marginTop: 12 };
+
+// The backdrop's alignment per placement. The modal centers its card; the
+// drawer and sheet let the absolutely-positioned surface anchor itself.
+export const backdropPlacement: Record<Placement, ViewStyle> = {
+  drawer: {},
+  sheet: {},
+  // items-center justify-center
+  modal: { alignItems: "center", justifyContent: "center" },
+};
+
+// The grabber/handle row: centered at the top of the sheet surface. The skin
+// supplies the pill dimensions/color; this centers it and spaces it from the
+// content below.
+export const handleWrap: ViewStyle = { alignItems: "center", marginBottom: 12 };
+
+// The centered title slot in the iOS 27 sheet header toolbar: it flexes to fill
+// the space between the two equal-size circular controls so the title stays
+// optically centered in the row. Used by the shell only when the active skin
+// draws the iOS sheet header.
+export const sheetHeaderTitleWrap: ViewStyle = { flex: 1, alignItems: "center", paddingHorizontal: 8 };
+
+// --- shared surface fragments -----------------------------------------------
+
+// The drawer anchors to the right edge, full height. Shared anchoring; the skin
+// owns fill/border/radius/padding/shadow.
+const DRAWER_ANCHOR: ViewStyle = { position: "absolute", top: 0, right: 0, bottom: 0, width: 300 };
+
+// The sheet anchors to the bottom edge, spanning the width. Shared anchoring.
+const SHEET_ANCHOR: ViewStyle = { position: "absolute", left: 0, right: 0, bottom: 0 };
+
+// The modal is a self-centered floating card.
+const MODAL_BOX: ViewStyle = { alignSelf: "center", marginVertical: 48, width: "100%", maxWidth: 420 };
+
+// ---------- Web: the established Canvas look (lifted verbatim) ----------
+// The current overlay surfaces: the drawer (absolute top-0 right-0 bottom-0
+// w-[300px] bg-popover border-l border-border p-5 shadow-xl), the sheet (absolute
+// left-0 right-0 bottom-0 bg-popover border-t border-border rounded-t-lg p-5
+// shadow-xl), and the modal (self-center my-12 w-full max-w-[420px] bg-popover
+// border border-border rounded-lg p-6 shadow-xl). No grabber handle on the web.
+export const webSkin: OverlaySkin = {
+  surface: (t, placement) => {
+    switch (placement) {
+      case "drawer":
+        return {
+          ...DRAWER_ANCHOR,
+          backgroundColor: t.popover,
+          borderLeftWidth: 1,
+          borderColor: t.border,
+          padding: 20,
+          ...shadow("xl"),
+        };
+      case "sheet":
+        return {
+          ...SHEET_ANCHOR,
+          backgroundColor: t.popover,
+          borderTopWidth: 1,
+          borderColor: t.border,
+          borderTopLeftRadius: 8,
+          borderTopRightRadius: 8,
+          padding: 20,
+          ...shadow("xl"),
+        };
+      case "modal":
+        return {
+          ...MODAL_BOX,
+          backgroundColor: t.popover,
+          borderWidth: 1,
+          borderColor: t.border,
+          borderRadius: 8,
+          padding: 24,
+          ...shadow("xl"),
+        };
+    }
+  },
+  handle: null,
+  // text-base font-semibold text-popover-foreground
+  title: (t) => ({ fontSize: 16, lineHeight: 24, fontWeight: "600", color: t["popover-foreground"] }),
+  // text-sm text-muted-foreground mt-2
+  description: (t) => ({ fontSize: 14, lineHeight: 20, color: t["muted-foreground"], marginTop: 8 }),
+  // flex-row justify-end mt-6
+  footer: { flexDirection: "row", justifyContent: "flex-end", marginTop: 24 },
+};
+
+// ---------- iOS 27 (Liquid Glass sheet): top corners ~38, grabber + header toolbar ----------
+// The iOS 27 sheet presents from the bottom with the TOP corners rounded ~38 (the
+// large continuous-corner radius of the Liquid Glass sheet) and a flat bottom; a
+// small grabber (a ~36x5 rounded muted-foreground pill) is centered at the top,
+// and an iOS 27 header toolbar sits directly below it: a leading CIRCULAR close (X)
+// button, a centered title, and a trailing CIRCULAR action button (a filled
+// `primary` accent circle). The right `drawer` keeps the lineless rounded-left
+// treatment; the centered `modal` becomes a rounded form-sheet card (~13 radius).
+// The iOS sheet is lineless: no visible border, a soft elevation.
+const IOS_SHEET_RADIUS = 38;
+const IOS_CARD_RADIUS = 13;
+// The header toolbar's circular control: a ~40pt circle behind the glyph.
+const IOS_HEADER_BUTTON = 40;
+export const iosSkin: OverlaySkin = {
+  surface: (t, placement) => {
+    switch (placement) {
+      case "drawer":
+        return {
+          ...DRAWER_ANCHOR,
+          backgroundColor: t.popover,
+          // The leading edge rounds (the panel slides in from the right edge).
+          borderTopLeftRadius: IOS_SHEET_RADIUS,
+          borderBottomLeftRadius: IOS_SHEET_RADIUS,
+          padding: 20,
+          ...shadow("xl"),
+        };
+      case "sheet":
+        return {
+          ...SHEET_ANCHOR,
+          backgroundColor: t.popover,
+          // Top corners rounded ~38, flat bottom (presents from the bottom edge).
+          borderTopLeftRadius: IOS_SHEET_RADIUS,
+          borderTopRightRadius: IOS_SHEET_RADIUS,
+          paddingHorizontal: 16,
+          // A little more top padding to seat the grabber above the header toolbar.
+          paddingTop: 8,
+          paddingBottom: 24,
+          ...shadow("xl"),
+        };
+      case "modal":
+        return {
+          ...MODAL_BOX,
+          // The iOS form sheet is a rounded card, lineless.
+          backgroundColor: t.popover,
+          borderRadius: IOS_CARD_RADIUS,
+          padding: 24,
+          ...shadow("xl"),
+        };
+    }
+  },
+  // The grabber: a ~36x5 rounded muted-foreground pill centered at the top.
+  handle: (t) => ({ width: 36, height: 5, borderRadius: 2.5, backgroundColor: t["muted-foreground"] }),
+  // SF-scale title: 17pt semibold (the iOS body emphasized).
+  title: (t) => ({ fontSize: 17, lineHeight: 22, fontWeight: "600", color: t["popover-foreground"] }),
+  // 15pt secondary text.
+  description: (t) => ({ fontSize: 15, lineHeight: 20, color: t["muted-foreground"], marginTop: 8 }),
+  footer: { flexDirection: "row", justifyContent: "flex-end", marginTop: 24 },
+  // iOS 27 sheet header toolbar: a 3-column row seating the leading/trailing
+  // circular controls and the centered title, just below the grabber.
+  sheetHeader: { flexDirection: "row", alignItems: "center", marginBottom: 12 },
+  // The circular tinted header button: a ~40pt `muted` circle centering its glyph.
+  headerButton: (t) => ({
+    width: IOS_HEADER_BUTTON,
+    height: IOS_HEADER_BUTTON,
+    borderRadius: IOS_HEADER_BUTTON / 2,
+    backgroundColor: t.muted,
+    alignItems: "center",
+    justifyContent: "center",
+  }),
+  // The filled-accent trailing header button: a ~40pt brand-`primary` circle.
+  headerButtonAccent: (t) => ({
+    width: IOS_HEADER_BUTTON,
+    height: IOS_HEADER_BUTTON,
+    borderRadius: IOS_HEADER_BUTTON / 2,
+    backgroundColor: t.primary,
+    alignItems: "center",
+    justifyContent: "center",
+  }),
+  // The centered header title: 17pt semibold, the iOS 27 sheet navigation title.
+  headerTitle: (t) => ({ fontSize: 17, lineHeight: 22, fontWeight: "600", color: t["popover-foreground"] }),
+};
+
+// ---------- Android (Material 3 bottom sheet): top corners 28, drag handle ----------
+// M3 modal bottom sheet: the `sheet` has its TOP corners rounded 28 (the M3
+// extra-large shape) with a centered drag handle (a ~32x4 rounded
+// muted-foreground pill), the `popover` surface, and M3 elevation. The right
+// `drawer` (navigation-drawer-like) keeps a large trailing radius; the centered
+// `modal` is the M3 dialog shape (28 radius, elevated, no border).
+const ANDROID_SHEET_RADIUS = 28;
+const ANDROID_DIALOG_RADIUS = 28;
+export const androidSkin: OverlaySkin = {
+  surface: (t, placement) => {
+    switch (placement) {
+      case "drawer":
+        return {
+          ...DRAWER_ANCHOR,
+          backgroundColor: t.popover,
+          // M3 navigation drawer: the trailing (leading-in) edge gets the large radius.
+          borderTopLeftRadius: ANDROID_SHEET_RADIUS,
+          borderBottomLeftRadius: ANDROID_SHEET_RADIUS,
+          padding: 24,
+          ...shadow("lg"),
+        };
+      case "sheet":
+        return {
+          ...SHEET_ANCHOR,
+          backgroundColor: t.popover,
+          // Top corners radius 28, flat bottom (M3 modal bottom sheet).
+          borderTopLeftRadius: ANDROID_SHEET_RADIUS,
+          borderTopRightRadius: ANDROID_SHEET_RADIUS,
+          paddingHorizontal: 24,
+          // Top padding seats the drag handle; M3 bottom-sheet content inset.
+          paddingTop: 16,
+          paddingBottom: 24,
+          ...shadow("lg"),
+        };
+      case "modal":
+        return {
+          ...MODAL_BOX,
+          // M3 dialog shape: 28 radius, elevated, no border.
+          backgroundColor: t.popover,
+          borderRadius: ANDROID_DIALOG_RADIUS,
+          padding: 24,
+          ...shadow("lg"),
+        };
+    }
+  },
+  // The M3 drag handle: a ~32x4 rounded muted-foreground pill centered at the top.
+  handle: (t) => ({ width: 32, height: 4, borderRadius: 2, backgroundColor: alpha(t["muted-foreground"], 0.4) }),
+  // M3 title: title-large-ish, 16sp medium on the surface.
+  title: (t) => ({ fontSize: 16, lineHeight: 24, fontWeight: "500", color: t["popover-foreground"] }),
+  // M3 body-medium supporting text.
+  description: (t) => ({ fontSize: 14, lineHeight: 20, color: t["muted-foreground"], marginTop: 8 }),
+  footer: { flexDirection: "row", justifyContent: "flex-end", marginTop: 24 },
+};

package/src/organisms/overlays/overlays.tsx

@@ -0,0 +1,6 @@
+import { createOverlay } from "./overlays.shared.js";
+import { webSkin } from "./overlays.styles.js";
+
+// Web Overlay (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Overlay = createOverlay(webSkin);
+export type { OverlayProps } from "./overlays.shared.js";

package/src/organisms/row-menu/row-menu.android.tsx

@@ -0,0 +1,6 @@
+import { createRowMenu } from "./row-menu.shared.js";
+import { androidSkin } from "./row-menu.styles.js";
+
+// Material 3 (menu) RowMenu. Metro resolves this file on Android; the docs import it for preview.
+export const RowMenu = createRowMenu(androidSkin);
+export type { RowMenuProps, RowMenuItem } from "./row-menu.shared.js";

package/src/organisms/row-menu/row-menu.ios.tsx

@@ -0,0 +1,6 @@
+import { createRowMenu } from "./row-menu.shared.js";
+import { iosSkin } from "./row-menu.styles.js";
+
+// iOS (HIG context menu) RowMenu. Metro resolves this file on iOS; the docs import it for preview.
+export const RowMenu = createRowMenu(iosSkin);
+export type { RowMenuProps, RowMenuItem } from "./row-menu.shared.js";

package/src/organisms/row-menu/row-menu.md

@@ -0,0 +1,102 @@
+# Row Menu
+
+Vertical action menu items and navigation links.
+
+## Usage
+
+```tsx
+<RowMenu
+  items={[
+    { label: "Edit" },
+    { label: "Duplicate" },
+    { label: "Delete", destructive: true, separatorBefore: true }
+  ]}
+/>
+```
+
+## Variants
+
+### Kind - links
+
+```tsx
+<RowMenu
+  links
+  items={[
+    { label: "Profile" },
+    { label: "Billing" },
+    { label: "Members" },
+    { label: "Settings" }
+  ]}
+/>
+```
+
+### Section label
+
+```tsx
+<RowMenu
+  sectionLabel="Actions"
+  items={[
+    { label: "Edit" },
+    { label: "Duplicate" },
+    { label: "Delete", destructive: true, separatorBefore: true }
+  ]}
+/>
+```
+
+### Leading icons
+
+```tsx
+<RowMenu
+  items={[
+    { label: "Edit", icon: "✎" },
+    { label: "Duplicate", icon: "⧉" },
+    { label: "Delete", icon: "🗑", destructive: true, separatorBefore: true }
+  ]}
+/>
+```
+
+## Do & Don't
+
+### Actions
+
+**Do** — Click an item: place destructive actions last, color them, and split them off with a divider.
+
+```tsx
+<RowMenu open items={[
+    { label: "Edit" },
+    { label: "Duplicate" },
+    { label: "Delete", destructive: true, separatorBefore: true }
+  ]} />
+```
+
+**Don't** — Click an item: a destructive action sandwiched between routine ones invites a costly misclick.
+
+```tsx
+<RowMenu open items={[
+    { label: "Edit" },
+    { label: "Delete", destructive: true },
+    { label: "Duplicate" }
+  ]} />
+```
+
+### Links
+
+**Do** — Use <a href> anchors so links behave like links, and mark the current page with an active highlight.
+
+```tsx
+<RowMenu open links items={[
+    { label: "Profile" },
+    { label: "Billing" },
+    { label: "Members" }
+  ]} />
+```
+
+**Don't** — Buttons can't be opened in a new tab, bookmarked, or middle-clicked, navigation needs real links.
+
+```tsx
+<RowMenu open items={[
+    { label: "Profile" },
+    { label: "Billing" },
+    { label: "Members" }
+  ]} />
+```