@shadow-js/ui 0.0.0-stage → 1.0.0

package/registry/message/message.tsx

@@ -0,0 +1,280 @@
+import { splitProps } from "@shadow-js/core";
+import type { ComponentProps, JSX } from "@shadow-js/web";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+/**
+ * The class list of a message row for each `align`. Use it to lay out any element like a message.
+ *
+ * @example
+ * ```tsx
+ * import { messageVariants } from "@/components/ui/message";
+ *
+ * export const Row = <div class={messageVariants({ align: "end" })}>Hello</div>;
+ * ```
+ * @since 1.0.0
+ * @see {@link Message}
+ */
+const messageVariants = cva("group/message flex w-full min-w-0 items-end gap-2", {
+  variants: {
+    align: {
+      start: "flex-row justify-start",
+      end: "flex-row-reverse justify-start",
+    },
+  },
+  defaultVariants: { align: "start" },
+});
+
+/**
+ * Props of {@link Message}: the attributes of a `div` plus `align`, which is `"start"` (the default, for
+ * the other side of the conversation) or `"end"` (for the reader's own messages).
+ * @since 1.0.0
+ * @see {@link Message}
+ */
+export type MessageProps = ComponentProps<"div"> & VariantProps<typeof messageVariants>;
+
+/**
+ * One row of a conversation. It lays out the avatar, the header, the message surface (a `Bubble`, a
+ * paragraph, a card) and the footer, and aligns them to the sender's side. The surface itself is a
+ * separate component, so a message can hold a bubble, rendered markdown or a tool call. Use
+ * {@link MessageGroup} to stack consecutive messages from one sender. For the scrolling container
+ * around the conversation, use `MessageScroller`.
+ *
+ * Keyboard and ARIA: a message is presentational and adds no role or keys; what it shows depends on
+ * the content inside. For an in-progress message, use a `Marker` with `role="status"` so assistive technology announces the update.
+ *
+ * Compared with shadcn/ui: `class` replaces `className`, and every part has a `data-slot`.
+ *
+ * @param props - The message props: `align`, `children` and the `div` attributes.
+ * @returns The message row.
+ * @example
+ * ```tsx
+ * import { Bubble, BubbleContent } from "@/components/ui/bubble";
+ * import { Message, MessageContent } from "@/components/ui/message";
+ *
+ * export function Greeting() {
+ *   return (
+ *     <Message>
+ *       <MessageContent>
+ *         <Bubble variant="muted">
+ *           <BubbleContent>How can I help you today?</BubbleContent>
+ *         </Bubble>
+ *       </MessageContent>
+ *     </Message>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageContent}
+ * @see {@link MessageAvatar}
+ * @see {@link MessageGroup}
+ */
+function Message(props: MessageProps): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "align"]);
+  return (
+    <div
+      data-slot="message"
+      data-align={local.align ?? "start"}
+      class={cn(messageVariants({ align: local.align }), local.class)}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Stacks consecutive messages from one sender. Give the earlier messages an empty {@link MessageAvatar} so
+ * they stay aligned with the avatar on the last one.
+ *
+ * Keyboard and ARIA: a plain `div` with no role and no keys.
+ *
+ * @param props - The `div` attributes and `class`.
+ * @returns The group.
+ * @example
+ * ```tsx
+ * import { Message, MessageContent, MessageGroup } from "@/components/ui/message";
+ *
+ * export function Burst() {
+ *   return (
+ *     <MessageGroup>
+ *       <Message>
+ *         <MessageContent>One</MessageContent>
+ *       </Message>
+ *       <Message>
+ *         <MessageContent>Two</MessageContent>
+ *       </Message>
+ *     </MessageGroup>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Message}
+ */
+function MessageGroup(props: ComponentProps<"div">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <div
+      data-slot="message-group"
+      class={cn("flex w-full flex-col gap-1", local.class)}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * The avatar slot beside the message, anchored to the bottom of the row. When the message has a
+ * {@link MessageFooter} the avatar sits level with the message surface, not with the footer. Render it empty
+ * (no children) to keep the space on earlier messages of a group.
+ *
+ * Keyboard and ARIA: a plain `div`; the avatar inside carries its own name.
+ *
+ * @param props - The `div` attributes and `class`.
+ * @returns The avatar slot.
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarFallback } from "@/components/ui/avatar";
+ * import { Message, MessageAvatar, MessageContent } from "@/components/ui/message";
+ *
+ * export function WithAvatar() {
+ *   return (
+ *     <Message>
+ *       <MessageAvatar>
+ *         <Avatar>
+ *           <AvatarFallback>AL</AvatarFallback>
+ *         </Avatar>
+ *       </MessageAvatar>
+ *       <MessageContent>Hello</MessageContent>
+ *     </Message>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Message}
+ */
+function MessageAvatar(props: ComponentProps<"div">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <div
+      data-slot="message-avatar"
+      class={cn(
+        "flex size-8 shrink-0 items-end justify-center group-has-data-[slot=message-footer]/message:mb-7",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Holds the header, the message surface and the footer in a column. It is as wide as its content, up to the
+ * width of the row, and follows the message's side.
+ *
+ * Keyboard and ARIA: a plain `div` with no role and no keys.
+ *
+ * @param props - The `div` attributes and `class`.
+ * @returns The content column.
+ * @example
+ * ```tsx
+ * import { MessageContent, MessageHeader } from "@/components/ui/message";
+ *
+ * export function Named() {
+ *   return (
+ *     <MessageContent>
+ *       <MessageHeader>Ada</MessageHeader>
+ *       <p>Hello</p>
+ *     </MessageContent>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Message}
+ */
+function MessageContent(props: ComponentProps<"div">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <div
+      data-slot="message-content"
+      class={cn(
+        "flex min-w-0 max-w-full flex-1 flex-col gap-1 group-data-[align=end]/message:items-end",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Content above the message surface, such as the sender's name. It is always aligned to the start,
+ * whatever the message's `align`.
+ *
+ * Keyboard and ARIA: a plain `div` with no role and no keys.
+ *
+ * @param props - The `div` attributes and `class`.
+ * @returns The header.
+ * @example
+ * ```tsx
+ * import { MessageHeader } from "@/components/ui/message";
+ *
+ * export const Sender = <MessageHeader>Ada Lovelace</MessageHeader>;
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageContent}
+ */
+function MessageHeader(props: ComponentProps<"div">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <div
+      data-slot="message-header"
+      class={cn("self-start px-1 text-xs text-muted-foreground", local.class)}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Content below the message surface: delivery status, a time, or actions such as copy and retry. It follows the
+ * message's side, so the actions of a message with `align="end"` sit at the end. Give each icon-only button an `aria-label`.
+ *
+ * Keyboard and ARIA: a plain `div` with no role and no keys; the buttons inside keep theirs.
+ *
+ * @param props - The `div` attributes and `class`.
+ * @returns The footer.
+ * @example
+ * ```tsx
+ * import { Button } from "@/components/ui/button";
+ * import { CopyIcon } from "@/components/ui/icons";
+ * import { MessageFooter } from "@/components/ui/message";
+ *
+ * export const Actions = (
+ *   <MessageFooter>
+ *     <Button variant="ghost" size="icon-sm" aria-label="Copy">
+ *       <CopyIcon />
+ *     </Button>
+ *   </MessageFooter>
+ * );
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageContent}
+ */
+function MessageFooter(props: ComponentProps<"div">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <div
+      data-slot="message-footer"
+      class={cn(
+        "flex items-center gap-1 text-xs text-muted-foreground group-data-[align=end]/message:justify-end",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+export {
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageFooter,
+  MessageGroup,
+  MessageHeader,
+  messageVariants,
+};

package/registry/message-scroller/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Message Scroller",
+  "description": "A chat transcript scroller that keeps the reader's place while a reply streams: anchored turns, following the newest text, history loading and a jump button."
+}

package/registry/message-scroller/message-scroller.tsx

@@ -0,0 +1,262 @@
+import { splitProps } from "@shadow-js/core";
+import {
+  type MessageScrollerButtonProps,
+  type MessageScrollerContentProps,
+  type MessageScrollerItemProps,
+  MessageScroller as MessageScrollerPrimitive,
+  type MessageScrollerProviderProps,
+  type MessageScrollerRootProps,
+  type MessageScrollerViewportProps,
+  type PolymorphicTarget,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+  useMessageScrollerVisibility,
+} from "@shadow-js/primitives";
+import type { JSX } from "@shadow-js/web";
+import { ArrowRightIcon } from "@/components/ui/icons";
+import { useUiStrings } from "@/lib/ui-strings";
+import { cn } from "@/lib/utils";
+
+/**
+ * The state of a conversation's scroller. It renders no element: put the {@link MessageScroller} frame, the viewport, the content and the rows inside it.
+ * Its props are the behavior: `autoScroll` follows the newest text while the reader stays at the bottom, `defaultScrollPosition` says where a saved
+ * thread opens (`"start"`, `"end"` or `"last-anchor"`), `scrollPreviousItemPeek` is how much of the row before a new turn stays visible, and
+ * `scrollMargin` and `scrollEdgeThreshold` tune the placement and the edges.
+ *
+ * Keyboard and ARIA: none of its own. See {@link MessageScrollerViewport}.
+ *
+ * @param props - The behavior props and the subtree.
+ * @returns The subtree.
+ * @example
+ * ```tsx
+ * import {
+ *   MessageScroller,
+ *   MessageScrollerButton,
+ *   MessageScrollerContent,
+ *   MessageScrollerItem,
+ *   MessageScrollerProvider,
+ *   MessageScrollerViewport,
+ * } from "@/components/ui/message-scroller";
+ *
+ * export function Thread() {
+ *   return (
+ *     <MessageScrollerProvider autoScroll>
+ *       <MessageScroller class="h-96">
+ *         <MessageScrollerViewport>
+ *           <MessageScrollerContent>
+ *             <MessageScrollerItem messageId="1" scrollAnchor>
+ *               Hello
+ *             </MessageScrollerItem>
+ *           </MessageScrollerContent>
+ *         </MessageScrollerViewport>
+ *         <MessageScrollerButton />
+ *       </MessageScroller>
+ *     </MessageScrollerProvider>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageScroller}
+ */
+function MessageScrollerProvider(props: MessageScrollerProviderProps): JSX.Element {
+  return <MessageScrollerPrimitive.Provider {...props} />;
+}
+
+/**
+ * The frame around the viewport and the button. It fills its parent, so put it in something with a height. The button is placed against it.
+ *
+ * Keyboard and ARIA: a plain `div`; none of its own. It carries `data-scrollable`, `data-autoscrolling` and `data-pending-scroll`.
+ *
+ * @param props - The frame props.
+ * @returns The frame.
+ * @example
+ * ```tsx
+ * import { MessageScroller, MessageScrollerProvider } from "@/components/ui/message-scroller";
+ *
+ * export const Frame = (
+ *   <MessageScrollerProvider>
+ *     <MessageScroller class="h-96" />
+ *   </MessageScrollerProvider>
+ * );
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageScrollerProvider}
+ */
+function MessageScroller<T extends PolymorphicTarget = "div">(
+  props: MessageScrollerRootProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as { readonly class?: string }, ["class"]);
+  return (
+    <MessageScrollerPrimitive.Root
+      data-slot="message-scroller"
+      class={cn("relative flex h-full min-h-0 w-full flex-col overflow-hidden", local.class)}
+      {...(rest as object)}
+    />
+  );
+}
+
+/**
+ * The scrollable region. It is a labeled landmark ("Messages") and a tab stop, so a keyboard user can scroll the thread with the arrow and page keys. It is hidden
+ * with `visibility` while the opening position is being applied, so a saved thread never visibly jumps. `preserveScrollOnPrepend` (on by default) keeps the row the
+ * reader is looking at still when older rows load above it.
+ *
+ * Keyboard and ARIA: `role="region"` named by the kit's string `messageScroller.label` (override with `aria-label`), `tabindex="0"`; the browser's own scroll keys.
+ *
+ * @param props - The viewport props.
+ * @returns The viewport.
+ * @example
+ * ```tsx
+ * import { MessageScrollerViewport } from "@/components/ui/message-scroller";
+ *
+ * export const Viewport = <MessageScrollerViewport aria-label="Conversation with Ada" />;
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageScrollerContent}
+ */
+function MessageScrollerViewport<T extends PolymorphicTarget = "div">(
+  props: MessageScrollerViewportProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as { readonly class?: string }, ["class"]);
+  const t = useUiStrings();
+  return (
+    <MessageScrollerPrimitive.Viewport
+      data-slot="message-scroller-viewport"
+      aria-label={t("messageScroller.label", "Messages")}
+      class={cn(
+        "size-full min-h-0 overflow-y-auto overscroll-contain outline-none focus-visible:ring-[3px] focus-visible:ring-inset focus-visible:ring-ring/50 data-[pending-scroll]:invisible focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-transparent",
+        local.class,
+      )}
+      {...(rest as object)}
+    />
+  );
+}
+
+/**
+ * The list of rows, a polite `log`: each row that is added is announced once. Pass `aria-busy` while a reply streams so the announcement waits until the message is complete. A
+ * column with a gap by default.
+ *
+ * Keyboard and ARIA: `role="log"` and `aria-relevant="additions"`; no keys. The spacer at its end is `aria-hidden`.
+ *
+ * @param props - The content props.
+ * @returns The content.
+ * @example
+ * ```tsx
+ * import { MessageScrollerContent } from "@/components/ui/message-scroller";
+ *
+ * export const Content = <MessageScrollerContent aria-busy={true} />;
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageScrollerItem}
+ */
+function MessageScrollerContent<T extends PolymorphicTarget = "div">(
+  props: MessageScrollerContentProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as { readonly class?: string }, ["class"]);
+  return (
+    <MessageScrollerPrimitive.Content
+      data-slot="message-scroller-content"
+      class={cn("flex min-h-full flex-col gap-4 p-4", local.class)}
+      {...(rest as object)}
+    />
+  );
+}
+
+/**
+ * One row of the thread. Give it a stable `messageId`, and `scrollAnchor` on the reader's own turn so a new question settles near the top. A row
+ * far from the window is not painted (`content-visibility: auto`) and keeps the size it last had, so a long thread stays cheap.
+ *
+ * Keyboard and ARIA: a plain `div`; none of its own.
+ *
+ * @param props - The row props: `messageId`, `scrollAnchor` and the `div` attributes.
+ * @returns The row.
+ * @example
+ * ```tsx
+ * import { MessageScrollerItem } from "@/components/ui/message-scroller";
+ *
+ * export const Row = (
+ *   <MessageScrollerItem messageId="42" scrollAnchor>
+ *     How do I add a dialog?
+ *   </MessageScrollerItem>
+ * );
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageScrollerContent}
+ */
+function MessageScrollerItem<T extends PolymorphicTarget = "div">(
+  props: MessageScrollerItemProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as { readonly class?: string }, ["class"]);
+  return (
+    <MessageScrollerPrimitive.Item
+      data-slot="message-scroller-item"
+      class={cn("[contain-intrinsic-size:auto_5rem] [content-visibility:auto]", local.class)}
+      {...(rest as object)}
+    />
+  );
+}
+
+/**
+ * A round button that scrolls to the end of the thread (or to the start with `direction="start"`). It fades out and leaves the tab order while there is nothing to
+ * scroll toward, and it sits at the bottom center of the frame. With no children it shows an arrow and no text; its name is the kit's string
+ * `messageScroller.toEnd` ("Scroll to latest") or `messageScroller.toStart`.
+ *
+ * Keyboard and ARIA: a native button (Enter and Space). Inactive, it is `inert` and `tabindex="-1"`.
+ *
+ * @param props - The button props: `direction`, `behavior` and the button attributes.
+ * @returns The button.
+ * @example
+ * ```tsx
+ * import { MessageScrollerButton } from "@/components/ui/message-scroller";
+ *
+ * export const Jump = <MessageScrollerButton />;
+ * ```
+ * @since 1.0.0
+ * @see {@link MessageScrollerProvider}
+ */
+function MessageScrollerButton<T extends PolymorphicTarget = "button">(
+  props: MessageScrollerButtonProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(
+    props as unknown as {
+      readonly class?: string;
+      readonly children?: JSX.Element;
+      readonly direction?: "start" | "end";
+    },
+    ["class", "children", "direction"],
+  );
+  const t = useUiStrings();
+  const start = (): boolean => local.direction === "start";
+  return (
+    <MessageScrollerPrimitive.Button
+      data-slot="message-scroller-button"
+      direction={local.direction}
+      aria-label={
+        start()
+          ? t("messageScroller.toStart", "Scroll to start")
+          : t("messageScroller.toEnd", "Scroll to latest")
+      }
+      class={cn(
+        "absolute start-1/2 z-10 inline-flex size-8 -translate-x-1/2 items-center justify-center rounded-full border bg-background text-foreground shadow-md outline-none transition-opacity hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50 rtl:translate-x-1/2 motion-reduce:transition-none data-[active=false]:pointer-events-none data-[active=false]:opacity-0 [&_svg]:size-4 focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-transparent",
+        start() ? "top-3" : "bottom-3",
+        local.class,
+      )}
+      {...(rest as object)}
+    >
+      {local.children ?? (
+        <ArrowRightIcon aria-hidden="true" class={start() ? "-rotate-90" : "rotate-90"} />
+      )}
+    </MessageScrollerPrimitive.Button>
+  );
+}
+
+export {
+  MessageScroller,
+  MessageScrollerButton,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerProvider,
+  MessageScrollerViewport,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+  useMessageScrollerVisibility,
+};

package/registry/native-select/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Native Select",
+  "description": "The browser's own select, styled like an input, with its picker and keyboard support."
+}

package/registry/native-select/native-select.tsx

@@ -0,0 +1,113 @@
+import { splitProps } from "@shadow-js/core";
+import type { ComponentProps, JSX } from "@shadow-js/web";
+import { ChevronDownIcon } from "@/components/ui/icons";
+import { cn } from "@/lib/utils";
+
+/**
+ * Props of {@link NativeSelect}: the attributes of the `select`, and its size.
+ * @since 1.0.0
+ * @see {@link NativeSelect}
+ */
+export type NativeSelectProps = ComponentProps<"select"> & {
+  /**
+   * The height of the control: `default` is 36px and `sm` is 32px.
+   * @default "default"
+   */
+  readonly size?: "sm" | "default" | undefined;
+};
+
+/**
+ * The browser's own select, in the kit's look: the operating system's picker and keyboard, styled
+ * like an input, with a chevron at the end (on the right in left-to-right text). Use
+ * {@link NativeSelectOption} and {@link NativeSelectOptGroup} for its options.
+ *
+ * Keyboard and ARIA: the keys are the native select's. The select has the `combobox` role and
+ * adds no ARIA attribute of its own. It has no visible name, so name it with `aria-label`, or with
+ * a {@link Label} whose `htmlFor` points at its `id`. `aria-invalid="true"`, which you pass, turns
+ * the border destructive.
+ *
+ * @param props The `select` attributes plus `size`. `class` styles the select itself; the chevron
+ * sits in the wrapper.
+ * @returns The wrapper `div` with the select and its chevron.
+ * @example
+ * import { NativeSelect, NativeSelectOption } from "@/components/ui/native-select";
+ *
+ * <NativeSelect aria-label="Country">
+ *   <NativeSelectOption value="se">Sweden</NativeSelectOption>
+ * </NativeSelect>
+ * @since 1.0.0
+ * @see {@link NativeSelectOption}
+ */
+function NativeSelect(props: NativeSelectProps): JSX.Element {
+  const [local, rest] = splitProps(props as NativeSelectProps & { readonly class?: unknown }, [
+    "class",
+    "size",
+  ]);
+  return (
+    <div data-slot="native-select-wrapper" class="group/native-select relative w-fit">
+      <select
+        data-slot="native-select"
+        data-size={(local.size as string | undefined) ?? "default"}
+        class={cn(
+          "h-9 w-full min-w-0 appearance-none rounded-md border border-input bg-transparent py-2 ps-3 pe-9 text-sm shadow-xs transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground dark:bg-input/30 dark:hover:bg-input/50",
+          // The small box is 32px: its padding shrinks with it, or the 20px text line is clipped.
+          "data-[size=sm]:h-8 data-[size=sm]:py-1",
+          "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 outline-none focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-transparent",
+          "aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40",
+          "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50",
+          local.class as string | undefined,
+        )}
+        {...rest}
+      />
+      <ChevronDownIcon
+        aria-hidden="true"
+        data-slot="native-select-icon"
+        class="pointer-events-none absolute top-1/2 end-3.5 size-4 -translate-y-1/2 opacity-50 select-none group-has-[:disabled]/native-select:opacity-30 rtl:-scale-x-100"
+      />
+    </div>
+  );
+}
+
+/**
+ * An option of a {@link NativeSelect}: a native `option` with its `value` and its label as text.
+ *
+ * Keyboard and ARIA: the select's keys choose it; the option has the `option` role of the browser.
+ *
+ * @param props The `option` attributes (`value`, `disabled`, `selected`); the children are its label.
+ * @returns The `option` element.
+ * @example
+ * import { NativeSelectOption } from "@/components/ui/native-select";
+ *
+ * <NativeSelectOption value="se">Sweden</NativeSelectOption>
+ * @since 1.0.0
+ * @see {@link NativeSelect}
+ */
+function NativeSelectOption(props: ComponentProps<"option">): JSX.Element {
+  return <option data-slot="native-select-option" {...props} />;
+}
+
+/**
+ * A labeled group of options of a {@link NativeSelect}: a native `optgroup`. Its `label` is shown
+ * as the group's heading in the picker.
+ *
+ * Keyboard and ARIA: no keys and no role of its own; the browser announces the `label` as the
+ * group's name.
+ *
+ * @param props The `optgroup` attributes, with `label` as the group's name. The children are the options.
+ * @returns The `optgroup` element.
+ * @example
+ * import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/ui/native-select";
+ *
+ * <NativeSelect aria-label="Country">
+ *   <NativeSelectOptGroup label="Nordic">
+ *     <NativeSelectOption value="se">Sweden</NativeSelectOption>
+ *   </NativeSelectOptGroup>
+ * </NativeSelect>
+ * @since 1.0.0
+ * @see {@link NativeSelectOption}
+ */
+function NativeSelectOptGroup(props: ComponentProps<"optgroup">): JSX.Element {
+  return <optgroup data-slot="native-select-optgroup" {...props} />;
+}
+
+export { NativeSelect, NativeSelectOptGroup, NativeSelectOption };

package/registry/navigation-menu/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Navigation Menu",
+  "description": "Site navigation with flyout content, keyboard arrows between triggers, Escape to close and focus return."
+}