@sableui/react 0.6.2 → 0.7.1

package/dist/components/menu/menu.meta.js

@@ -0,0 +1,176 @@
+// src/components/menu/menu.meta.ts
+var menuMeta = {
+  name: "Menu",
+  summary: "Dropdown menu over Base UI Menu \u2014 roving focus, typeahead, ARIA menu/menuitem wiring, collision-aware positioning, Esc/outside dismissal. Trigger + portal-rendered popup with items, groups, and separators.",
+  status: "stable",
+  keywords: [
+    "menu",
+    "dropdown",
+    "actions",
+    "commands"
+  ],
+  usage: {
+    description: "Use Menu for a compact list of actions opened from a visible trigger.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for secondary or grouped commands that do not need to be visible all the time."
+      },
+      {
+        guidance: "do",
+        description: "Keep item labels action-oriented and easy to scan."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Menu for complex forms, persistent navigation, or arbitrary rich content."
+      },
+      {
+        guidance: "dont",
+        description: "Do not build a Select out of it. A menu fires actions and has no value; a Select holds one and reports changes. Swapping them loses form semantics and keyboard type-ahead."
+      },
+      {
+        guidance: "do",
+        description: "Inside a <Workspace> a Menu adapts automatically \u2014 its popup re-applies the compact density across the portal, so items render on the chrome type tier and the control ladder resolves to workspace sizes. Do NOT override the size per call site; that was necessary before v0.41 and is now drift."
+      }
+    ],
+    anatomy: [
+      {
+        name: "MenuTrigger",
+        required: true,
+        description: "The control that opens the menu."
+      },
+      {
+        name: "MenuContent",
+        required: true,
+        description: "The floating command surface."
+      },
+      {
+        name: "MenuItem",
+        required: true,
+        description: "One selectable command."
+      },
+      {
+        name: "MenuSeparator",
+        required: false,
+        description: "A divider between groups."
+      },
+      {
+        name: "MenuGroup",
+        required: false,
+        description: "A grouped set of menu items."
+      },
+      {
+        name: "MenuGroupLabel",
+        required: false,
+        description: "A label for a group of items."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "ContextMenu",
+      "OverflowMenu"
+    ]
+  },
+  props: [
+    {
+      name: "Menu (Root)",
+      type: "Base UI Menu.Root props (open, defaultOpen, onOpenChange, modal, orientation, loopFocus)",
+      default: "\u2014",
+      description: "Groups all parts and controls open state. Uncontrolled by default."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "MenuTrigger",
+      type: "Base UI Menu.Trigger props + render",
+      description: "The button that opens the menu. Compose with render={<Button \u2026 />}."
+    },
+    {
+      name: "MenuContent",
+      type: "Base UI Popup props + side: 'top' | 'right' | 'bottom' | 'left' + align: 'start' | 'center' | 'end' + sideOffset: number + className",
+      description: "Portal + Positioner + Popup. side picks which side of the trigger the popup renders against (auto-flips on collision; defaults to 'bottom'); align sets alignment along that side (defaults to 'start'); sideOffset is the gap in px between trigger and popup (defaults to 6)."
+    },
+    {
+      name: "MenuItem",
+      type: 'Base UI Menu.Item props + className (disabled, closeOnClick, onClick) + variant?: "default" | "destructive"',
+      description: 'An interactive row. Highlights via data-[highlighted]; dims via data-[disabled]. variant="destructive" for a delete or irreversible action: it keeps the destructive ink when highlighted (never className="text-destructive", which the highlight repaints).'
+    },
+    {
+      name: "MenuSeparator",
+      type: "Base UI Separator props + className",
+      description: "Hairline rule between item runs."
+    },
+    {
+      name: "MenuSubmenu",
+      type: "Base UI Menu.SubmenuRoot props",
+      description: 'A nested menu. Wraps a MenuSubmenuTrigger and its own MenuContent \u2014 pass side="inline-end" to that content so the submenu opens away from its parent in RTL as well as LTR.'
+    },
+    {
+      name: "MenuSubmenuTrigger",
+      type: "Base UI Menu.SubmenuTrigger props + value: ReactNode + className",
+      description: 'The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High \u203A" rather than making the reader open it to find out.'
+    },
+    {
+      name: "MenuRadioGroup",
+      type: "Base UI Menu.RadioGroup props (value, defaultValue, onValueChange)",
+      description: "A single-choice group inside a menu. Controlled via value/onValueChange, uncontrolled via defaultValue."
+    },
+    {
+      name: "MenuRadioItem",
+      type: "Base UI Menu.RadioItem props + className (value, disabled)",
+      description: "One option in a MenuRadioGroup, rendered as menuitemradio with a real checked state. The check sits in a reserved leading column so labels never shift sideways as the highlight moves."
+    },
+    {
+      name: "MenuCheckboxItem",
+      type: "Base UI Menu.CheckboxItem props + className + { checked?: boolean; defaultChecked?: boolean; onCheckedChange?: (checked: boolean) => void; disabled?: boolean }",
+      description: "A toggling row, with the same reserved leading column as MenuRadioItem so a menu mixing the two keeps one text margin."
+    },
+    {
+      name: "MenuGroup",
+      type: "Base UI Menu.Group props + className",
+      description: "Groups related items; pair with MenuGroupLabel for an accessible group name."
+    },
+    {
+      name: "MenuGroupLabel",
+      type: "Base UI Menu.GroupLabel props + className",
+      description: "The label for a MenuGroup \u2014 auto-associated with the group for screen readers."
+    }
+  ],
+  tokensUsed: [
+    "popover",
+    "popover-foreground",
+    "border",
+    "accent",
+    "accent-foreground",
+    "muted-foreground"
+  ],
+  a11y: [
+    "Base UI provides role=menu/menuitem, roving tabindex, arrow-key navigation, and typeahead.",
+    "Esc and outside-press dismiss; focus returns to the trigger on close.",
+    "Animate open/close via data-[starting-style]/data-[ending-style] attributes.",
+    "MenuGroupLabel is auto-associated with its MenuGroup for screen readers.",
+    "A disabled MenuItem stays in the arrow-key order \u2014 Base UI keeps it focusable with aria-disabled so screen-reader users learn the command exists \u2014 but it cannot be activated, and it ignores the pointer."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: '<Menu><MenuTrigger render={<Button variant="secondary">Options</Button>} /><MenuContent><MenuItem>Edit</MenuItem><MenuItem>Duplicate</MenuItem><MenuSeparator /><MenuItem variant="destructive">Delete</MenuItem></MenuContent></Menu>'
+    },
+    {
+      label: "Grouped",
+      code: '<Menu><MenuTrigger render={<Button variant="secondary">Account</Button>} /><MenuContent><MenuGroup><MenuGroupLabel>Signed in</MenuGroupLabel><MenuItem>Profile</MenuItem><MenuItem>Settings</MenuItem></MenuGroup><MenuSeparator /><MenuItem>Sign out</MenuItem></MenuContent></Menu>'
+    },
+    {
+      label: "Nested, with a single-choice submenu",
+      code: '<Menu>\n	<MenuTrigger render={<Button variant="secondary">View</Button>} />\n	<MenuContent>\n		<MenuItem>Reload</MenuItem>\n		<MenuSubmenu>\n			<MenuSubmenuTrigger value={density}>Density</MenuSubmenuTrigger>\n			<MenuContent side="inline-end" align="start" sideOffset={4}>\n				<MenuRadioGroup value={density} onValueChange={setDensity}>\n					<MenuRadioItem value="Comfortable">Comfortable</MenuRadioItem>\n					<MenuRadioItem value="Compact">Compact</MenuRadioItem>\n				</MenuRadioGroup>\n			</MenuContent>\n		</MenuSubmenu>\n	</MenuContent>\n</Menu>'
+    },
+    {
+      label: "Toggling rows",
+      code: '<Menu>\n	<MenuTrigger render={<Button variant="secondary">Columns</Button>} />\n	<MenuContent>\n		<MenuCheckboxItem checked={cols.status} onCheckedChange={(v) => setCol("status", v)}>Status</MenuCheckboxItem>\n		<MenuCheckboxItem checked={cols.updated} onCheckedChange={(v) => setCol("updated", v)}>Updated</MenuCheckboxItem>\n	</MenuContent>\n</Menu>'
+    }
+  ]
+};
+export {
+  menuMeta
+};

package/dist/components/message/index.js

@@ -0,0 +1,7 @@
+// src/components/message/index.ts
+import { Message } from "./message.js";
+import { messageMeta } from "./message.meta.js";
+export {
+  Message,
+  messageMeta
+};

package/dist/components/message/message.js

@@ -0,0 +1,83 @@
+// src/components/message/message.tsx
+import { cn } from "../../lib/cn.js";
+import { useTypeTier } from "../../lib/density.js";
+import {
+  messageAvatarVariants,
+  messageBodyVariants,
+  messageVariants
+} from "./message.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var AVATAR_WIDTHS = {
+  sm: "w-8",
+  md: "w-10",
+  lg: "w-12"
+};
+var AVATAR_ROW_HEIGHTS = {
+  sm: "min-h-8",
+  md: "min-h-10",
+  lg: "min-h-12"
+};
+function Message({
+  messageId,
+  align = "start",
+  avatar,
+  avatarSize = "sm",
+  header,
+  footer,
+  grouped = false,
+  className,
+  children,
+  ...props
+}) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-message-id": messageId,
+      "data-align": align,
+      "data-grouped": grouped ? "" : void 0,
+      className: cn(messageVariants({ align, grouped }), className),
+      ...props,
+      children: [
+        avatar || grouped ? /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: cn(
+              messageAvatarVariants({ align }),
+              AVATAR_WIDTHS[avatarSize]
+            ),
+            children: grouped ? null : avatar
+          }
+        ) : null,
+        /* @__PURE__ */ jsxs("div", { className: cn(messageBodyVariants({ align })), children: [
+          header ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: cn(
+                "flex items-center text-muted-foreground",
+                avatar && !grouped && AVATAR_ROW_HEIGHTS[avatarSize],
+                tier.secondary
+              ),
+              children: /* @__PURE__ */ jsx("div", { className: "flex items-baseline gap-2", children: header })
+            }
+          ) : null,
+          children,
+          footer ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: cn(
+                "flex items-center gap-2 text-muted-foreground",
+                tier.secondary
+              ),
+              children: footer
+            }
+          ) : null
+        ] })
+      ]
+    }
+  );
+}
+Message.displayName = "Message";
+export {
+  Message
+};

package/dist/components/message/message.meta.js

@@ -0,0 +1,150 @@
+// src/components/message/message.meta.ts
+var messageMeta = {
+  name: "Message",
+  summary: "One row in a conversation: avatar gutter, side, and stacked header / content / footer. Layout only \u2014 the surface is Bubble, passed as children.",
+  status: "stable",
+  keywords: [
+    "chat",
+    "message",
+    "conversation row",
+    "turn",
+    "thread",
+    "messaging",
+    "grouped messages",
+    "ai chat"
+  ],
+  usage: {
+    description: "The row a single turn occupies. It owns the geometry \u2014 which side, the avatar gutter, where the name and timestamp go, where reactions and receipts go \u2014 and nothing about how the content looks. That separation is the point: an assistant's markdown answer, a one-line reply, an attachment, and a tool-call card are all the same row with different children.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Set `messageId`. It is what MessageScroller reads for `scrollToMessage`, `initialScroll`, and visibility tracking \u2014 a message without one cannot be jumped to or marked as read."
+      },
+      {
+        guidance: "do",
+        description: "Pass the same `align` to Message and to the Bubble inside it, so the flattened tail corner lands on the speaker's side."
+      },
+      {
+        guidance: "do",
+        description: "Use `grouped` for consecutive messages from one author. It tightens the spacing and hides the avatar while keeping its column reserved, so the run reads as one block instead of stepping left. Pass `tail={false}` to the Bubble in each continuation too, so only the first message in the run carries a tail."
+      },
+      {
+        guidance: "do",
+        description: "Match `avatarSize` to the `size` of the Avatar you pass (sm/md/lg line up 1:1). The gutter is declared, not measured, because it has to hold its width when `grouped` hides the avatar."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not justify the content to move a message to the right. `align="end"` already mirrors the whole row, gutter included; adding your own justification fights it.'
+      },
+      {
+        guidance: "dont",
+        description: 'Do not put the timestamp inside the Bubble. It belongs in `header` or `footer`, which stay outside the surface so `variant="plain"` content still has one.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not reach for Message to lay out a system note or a date break. That is `Marker`, which is deliberately quieter than the message tier."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Avatar gutter",
+        required: false,
+        description: "Fixed-width column for the author's Avatar. Kept (but emptied) when `grouped`, which is what keeps a run aligned."
+      },
+      {
+        name: "Header",
+        required: false,
+        description: "Author name and timestamp, above the content."
+      },
+      {
+        name: "Content",
+        required: true,
+        description: "The children \u2014 usually a Bubble, but equally an Attachment, a tool card, or plain rendered markdown."
+      },
+      {
+        name: "Footer",
+        required: false,
+        description: "Reactions, delivery receipts, retry actions."
+      }
+    ]
+  },
+  related: {
+    components: ["Bubble", "MessageScroller", "Marker", "Attachment", "Avatar"]
+  },
+  props: [
+    {
+      name: "messageId",
+      type: "string",
+      description: "Stable id, published as `data-message-id`. The handle MessageScroller uses for scroll commands and visibility tracking."
+    },
+    {
+      name: "align",
+      type: '"start" | "end"',
+      default: '"start"',
+      description: 'Which side of the conversation. "start" is the other party or the assistant; "end" is the person reading. Mirrors the whole row, gutter included.'
+    },
+    {
+      name: "avatar",
+      type: "ReactNode",
+      description: "Avatar node for the gutter. Omit for a message with no author identity."
+    },
+    {
+      name: "avatarSize",
+      type: '"sm" | "md" | "lg"',
+      default: '"sm"',
+      description: "Gutter width, matching Avatar's own size scale 1:1 (32 / 40 / 48px). Declared rather than measured so it survives `grouped`."
+    },
+    {
+      name: "header",
+      type: "ReactNode",
+      description: "Author name, timestamp \u2014 anything above the content."
+    },
+    {
+      name: "footer",
+      type: "ReactNode",
+      description: "Reactions, receipts, retry actions \u2014 anything below the content."
+    },
+    {
+      name: "grouped",
+      type: "boolean",
+      default: "false",
+      description: "This message continues a run from the same author: tightens the spacing (via `--message-gap`) and drops the avatar while reserving its column."
+    },
+    {
+      name: "...div props",
+      type: 'Omit<ComponentPropsWithRef<"div">, "id">',
+      description: "Spread onto the row. Use `messageId` rather than `id` \u2014 the scroller matches on `data-message-id`."
+    }
+  ],
+  variants: {
+    align: ["start", "end"],
+    avatarSize: ["sm", "md", "lg"]
+  },
+  tokensUsed: ["foreground", "muted-foreground"],
+  a11y: [
+    "A plain container with no imposed role \u2014 the conversation's semantics belong to the list or log element you wrap it in, not to each row.",
+    "`align` reverses the visual row without reordering the DOM, so reading order in assistive tech stays chronological regardless of which side a message is on.",
+    "The header and footer render at the secondary type step in muted ink, keeping both below the message tier in the visual hierarchy without dropping either below the AA contrast floor."
+  ],
+  examples: [
+    {
+      label: "Incoming and outgoing",
+      code: '<>\n	<Message messageId="m1" avatar={<Avatar size="sm" fallback="CA" />} header={<><strong className="text-foreground">Carla</strong><RelativeTime date={sentAt} /></>}>\n		<Bubble>Did the deploy finish?</Bubble>\n	</Message>\n	<Message messageId="m2" align="end">\n		<Bubble variant="primary" align="end">Green across the board.</Bubble>\n	</Message>\n</>'
+    },
+    {
+      label: "A grouped run",
+      code: '<>\n	<Message messageId="m1" avatar={<Avatar size="sm" fallback="CA" />} header={<strong className="text-foreground">Carla</strong>}>\n		<Bubble>One more thing.</Bubble>\n	</Message>\n	<Message messageId="m2" grouped>\n		<Bubble tail={false}>The staging cert expires Friday.</Bubble>\n	</Message>\n</>'
+    },
+    {
+      label: "With reactions in the footer",
+      code: '<Message messageId="m3" avatar={<Avatar size="sm" fallback="JR" />} footer={<BubbleReactions><BubbleReaction emoji="\u{1F389}" count={3} active /><BubbleReaction emoji="\u{1F440}" /></BubbleReactions>}>\n	<Bubble>Shipped 0.45.0.</Bubble>\n</Message>'
+    },
+    {
+      label: "An attachment as the content",
+      code: '<Message messageId="m4" align="end">\n	<Attachment name="proposal.pdf" meta="2.4 MB \xB7 PDF" />\n</Message>'
+    }
+  ]
+};
+export {
+  messageMeta
+};

package/dist/components/message/message.variants.js

@@ -0,0 +1,41 @@
+// src/components/message/message.variants.ts
+import { cva } from "class-variance-authority";
+var messageVariants = cva("group/message flex w-full", {
+  variants: {
+    align: {
+      start: "flex-row",
+      end: "flex-row-reverse"
+    },
+    grouped: {
+      true: "-mt-[calc(var(--message-gap,calc(var(--spacing)*4))-var(--spacing))]",
+      false: ""
+    }
+  },
+  defaultVariants: {
+    align: "start",
+    grouped: false
+  }
+});
+var messageAvatarVariants = cva("shrink-0", {
+  variants: {
+    align: {
+      start: "mr-3",
+      end: "ml-3"
+    }
+  },
+  defaultVariants: { align: "start" }
+});
+var messageBodyVariants = cva("flex min-w-0 flex-col gap-1", {
+  variants: {
+    align: {
+      start: "items-start",
+      end: "items-end"
+    }
+  },
+  defaultVariants: { align: "start" }
+});
+export {
+  messageAvatarVariants,
+  messageBodyVariants,
+  messageVariants
+};

package/dist/components/message-scroller/index.js

@@ -0,0 +1,9 @@
+// src/components/message-scroller/index.ts
+import {
+  MessageScroller
+} from "./message-scroller.js";
+import { messageScrollerMeta } from "./message-scroller.meta.js";
+export {
+  MessageScroller,
+  messageScrollerMeta
+};