@shadow-js/ui 0.0.0-stage → 1.0.0

package/registry/breadcrumb/breadcrumb.tsx

@@ -0,0 +1,354 @@
+import { splitProps } from "@shadow-js/core";
+import { Polymorphic, type PolymorphicProps, type PolymorphicTarget } from "@shadow-js/primitives";
+import type { ComponentProps, JSX } from "@shadow-js/web";
+import { ChevronRightIcon, EllipsisIcon } from "@/components/ui/icons";
+import { useUiStrings } from "@/lib/ui-strings";
+import { type ClassValue, cn } from "@/lib/utils";
+
+/**
+ * A trail of links that shows where the current page sits in the site. It renders a `nav` with
+ * the accessible name "breadcrumb" and holds a {@link BreadcrumbList}.
+ *
+ * Keyboard and ARIA: the links are native anchors, so Tab moves between them and Enter follows
+ * one. The current page is marked with `aria-current="page"` (see {@link BreadcrumbPage}). The
+ * separators are hidden from assistive technology.
+ *
+ * Compared with shadcn/ui: `class` replaces `className`, `as` replaces `asChild` on
+ * {@link BreadcrumbLink}, and every element carries `data-slot`.
+ *
+ * @param props - The navigation props: `children` and the `nav` attributes.
+ * @returns The navigation element.
+ * @example
+ * ```tsx
+ * import {
+ *   Breadcrumb,
+ *   BreadcrumbItem,
+ *   BreadcrumbLink,
+ *   BreadcrumbList,
+ *   BreadcrumbPage,
+ *   BreadcrumbSeparator,
+ * } from "@/components/ui/breadcrumb";
+ *
+ * export function Trail() {
+ *   return (
+ *     <Breadcrumb>
+ *       <BreadcrumbList>
+ *         <BreadcrumbItem>
+ *           <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *         </BreadcrumbItem>
+ *         <BreadcrumbSeparator />
+ *         <BreadcrumbItem>
+ *           <BreadcrumbPage>Components</BreadcrumbPage>
+ *         </BreadcrumbItem>
+ *       </BreadcrumbList>
+ *     </Breadcrumb>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BreadcrumbList}
+ * @see {@link BreadcrumbLink}
+ */
+function Breadcrumb(props: ComponentProps<"nav">): JSX.Element {
+  const [local, rest] = splitProps(props, ["children"]);
+  const t = useUiStrings();
+  return (
+    <nav aria-label={t("breadcrumb.label", "breadcrumb")} data-slot="breadcrumb" {...rest}>
+      {local.children}
+    </nav>
+  );
+}
+
+/**
+ * The ordered list of the trail. Each step is a {@link BreadcrumbItem}, and the steps are read in
+ * order.
+ *
+ * @param props - The list props: `class`, `children`, and the `ol` attributes.
+ * @returns The list element.
+ * @example
+ * ```tsx
+ * import {
+ *   Breadcrumb,
+ *   BreadcrumbItem,
+ *   BreadcrumbLink,
+ *   BreadcrumbList,
+ * } from "@/components/ui/breadcrumb";
+ *
+ * export function Steps() {
+ *   return (
+ *     <Breadcrumb>
+ *       <BreadcrumbList>
+ *         <BreadcrumbItem>
+ *           <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+ *         </BreadcrumbItem>
+ *       </BreadcrumbList>
+ *     </Breadcrumb>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Breadcrumb}
+ * @see {@link BreadcrumbItem}
+ */
+function BreadcrumbList(props: ComponentProps<"ol">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "children"]);
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      class={cn(
+        "flex flex-wrap items-center gap-1.5 text-sm wrap-break-word text-muted-foreground sm:gap-2.5",
+        local.class,
+      )}
+      {...rest}
+    >
+      {local.children}
+    </ol>
+  );
+}
+
+/**
+ * One step of the trail: a link, the current page or an ellipsis. It renders an `li` inside a
+ * {@link BreadcrumbList}.
+ *
+ * @param props - The item props: `class`, `children`, and the `li` attributes.
+ * @returns The item element.
+ * @example
+ * ```tsx
+ * import { BreadcrumbItem, BreadcrumbLink, BreadcrumbList } from "@/components/ui/breadcrumb";
+ *
+ * export function DocsStep() {
+ *   return (
+ *     <BreadcrumbList>
+ *       <BreadcrumbItem>
+ *         <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+ *       </BreadcrumbItem>
+ *     </BreadcrumbList>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BreadcrumbList}
+ */
+function BreadcrumbItem(props: ComponentProps<"li">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "children"]);
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      class={cn("inline-flex items-center gap-1.5", local.class)}
+      {...rest}
+    >
+      {local.children}
+    </li>
+  );
+}
+
+/** The props as the implementation sees them. */
+type Loose = {
+  readonly as?: PolymorphicTarget;
+  readonly class?: ClassValue;
+  readonly [prop: string]: unknown;
+};
+
+/**
+ * Props of {@link BreadcrumbLink}: every attribute of the chosen element. The element is an `a`
+ * by default; the `as` prop picks another one.
+ * @since 1.0.0
+ * @see {@link BreadcrumbLink}
+ */
+export type BreadcrumbLinkProps<T extends PolymorphicTarget = "a"> = PolymorphicProps<
+  "a",
+  object,
+  T
+>;
+
+/**
+ * A link to an earlier step of the trail. It renders an `a` with `href`. Use `as` to render your
+ * router's link component instead, which keeps the same styles.
+ *
+ * Keyboard and ARIA: a native link. Tab focuses it and Enter follows it. The link's accessible name
+ * is its text.
+ *
+ * @param props - The link props: `href`, `as`, `children`, and the attributes of the element.
+ * @returns The link element.
+ * @example
+ * ```tsx
+ * import { BreadcrumbItem, BreadcrumbLink } from "@/components/ui/breadcrumb";
+ *
+ * export function HomeLink() {
+ *   return (
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BreadcrumbLinkProps}
+ * @see {@link BreadcrumbPage}
+ */
+function BreadcrumbLink<T extends PolymorphicTarget = "a">(
+  props: BreadcrumbLinkProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as Loose, ["as", "class"]);
+  return (
+    <Polymorphic
+      as={local.as ?? "a"}
+      data-slot="breadcrumb-link"
+      class={cn(
+        "transition-colors hover:text-foreground motion-reduce:transition-none",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * The current page: the last step of the trail. It is not a link.
+ *
+ * Keyboard and ARIA: the element is a `span` with `aria-current="page"`, `role="link"` and
+ * `aria-disabled="true"`, so assistive technology announces a disabled link that is the current
+ * page. It has no `href` and no `tabindex`, so it is not focusable.
+ *
+ * @param props - The page props: `children` and the `span` attributes.
+ * @returns The page element.
+ * @example
+ * ```tsx
+ * import { BreadcrumbItem, BreadcrumbPage } from "@/components/ui/breadcrumb";
+ *
+ * export function CurrentPage() {
+ *   return (
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BreadcrumbLink}
+ */
+function BreadcrumbPage(props: ComponentProps<"span">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "children"]);
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      role="link"
+      aria-disabled="true"
+      aria-current="page"
+      class={cn("font-normal text-foreground", local.class)}
+      {...rest}
+    >
+      {local.children}
+    </span>
+  );
+}
+
+/**
+ * The divider between two steps. By default it is a chevron that flips in right-to-left layouts;
+ * pass children to show your own divider, such as `/`.
+ *
+ * Keyboard and ARIA: the separator is `role="presentation"` and `aria-hidden="true"`, so assistive
+ * technology skips it.
+ *
+ * @param props - The separator props: `children` and the `li` attributes.
+ * @returns The separator element.
+ * @example
+ * ```tsx
+ * import {
+ *   Breadcrumb,
+ *   BreadcrumbItem,
+ *   BreadcrumbLink,
+ *   BreadcrumbList,
+ *   BreadcrumbPage,
+ *   BreadcrumbSeparator,
+ * } from "@/components/ui/breadcrumb";
+ *
+ * export function SlashTrail() {
+ *   return (
+ *     <Breadcrumb>
+ *       <BreadcrumbList>
+ *         <BreadcrumbItem>
+ *           <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *         </BreadcrumbItem>
+ *         <BreadcrumbSeparator>/</BreadcrumbSeparator>
+ *         <BreadcrumbItem>
+ *           <BreadcrumbPage>Docs</BreadcrumbPage>
+ *         </BreadcrumbItem>
+ *       </BreadcrumbList>
+ *     </Breadcrumb>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BreadcrumbList}
+ */
+function BreadcrumbSeparator(props: ComponentProps<"li">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "children"]);
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      class={cn("[&>svg]:size-3.5", local.class)}
+      {...rest}
+    >
+      {local.children ?? <ChevronRightIcon class="rtl:rotate-180" />}
+    </li>
+  );
+}
+
+/**
+ * Stands for collapsed steps of a long trail. Put a menu trigger around it to reveal the hidden
+ * steps. It is an item of the list, so it goes inside a {@link BreadcrumbItem}.
+ *
+ * Keyboard and ARIA: the ellipsis is `role="presentation"` and `aria-hidden="true"`, so assistive
+ * technology does not announce the collapsed steps. It has no keys of its own.
+ *
+ * @param props - The ellipsis props: the `span` attributes.
+ * @returns The ellipsis element.
+ * @example
+ * ```tsx
+ * import {
+ *   BreadcrumbEllipsis,
+ *   BreadcrumbItem,
+ *   BreadcrumbList,
+ * } from "@/components/ui/breadcrumb";
+ *
+ * export function Collapsed() {
+ *   return (
+ *     <BreadcrumbList>
+ *       <BreadcrumbItem>
+ *         <BreadcrumbEllipsis />
+ *       </BreadcrumbItem>
+ *     </BreadcrumbList>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BreadcrumbItem}
+ */
+function BreadcrumbEllipsis(props: ComponentProps<"span">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  const t = useUiStrings();
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      role="presentation"
+      class={cn("flex size-9 items-center justify-center", local.class)}
+      {...rest}
+    >
+      <EllipsisIcon class="size-4" aria-hidden="true" />
+      <span class="sr-only">{t("breadcrumb.more", "More")}</span>
+    </span>
+  );
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+};

package/registry/breadcrumb/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Breadcrumb",
+  "description": "Displays the path to the current resource using a hierarchy of links."
+}

package/registry/bubble/bubble.tsx

@@ -0,0 +1,260 @@
+import { splitProps } from "@shadow-js/core";
+import { Polymorphic, type PolymorphicProps, type PolymorphicTarget } from "@shadow-js/primitives";
+import type { ComponentProps, JSX } from "@shadow-js/web";
+import { cva, type VariantProps } from "class-variance-authority";
+import { type ClassValue, cn } from "@/lib/utils";
+
+/**
+ * The class list of a bubble's frame for each `variant` and `align`. The look of the text surface is on
+ * {@link BubbleContent}, which reads the variant from this element; this list is the box around it.
+ *
+ * @example
+ * ```tsx
+ * import { bubbleVariants } from "@/components/ui/bubble";
+ *
+ * export function Frame() {
+ *   return <div class={bubbleVariants({ align: "end" })}>Custom row</div>;
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Bubble}
+ */
+const bubbleVariants = cva("group/bubble relative flex min-w-0 flex-col", {
+  variants: {
+    variant: {
+      default: "",
+      secondary: "",
+      muted: "",
+      tinted: "",
+      outline: "",
+      ghost: "w-full max-w-full",
+      destructive: "",
+    },
+    align: {
+      start: "me-auto items-start",
+      end: "ms-auto items-end",
+    },
+  },
+  compoundVariants: [
+    {
+      variant: ["default", "secondary", "muted", "tinted", "outline", "destructive"],
+      class: "w-fit max-w-[85%]",
+    },
+  ],
+  defaultVariants: { variant: "default", align: "start" },
+});
+
+/**
+ * Props of {@link Bubble}: the attributes of a `div` plus `variant` (`"default"`, `"secondary"`,
+ * `"muted"`, `"tinted"`, `"outline"`, `"ghost"` or `"destructive"`) and `align` (`"start"` or `"end"`).
+ * @since 1.0.0
+ * @see {@link Bubble}
+ */
+export type BubbleProps = ComponentProps<"div"> & VariantProps<typeof bubbleVariants>;
+
+/**
+ * A framed message in a conversation: a {@link BubbleContent} with an optional {@link BubbleReactions}.
+ * `variant` picks the surface and `align` the side. A `ghost` bubble has no frame and uses the full width,
+ * for a reply that reads as a document. In a chat, set `align` on a {@link Message} instead, which aligns the bubbles inside it.
+ *
+ * Keyboard and ARIA: a bubble has no role and no keys. Color is never the only signal: tell sender and meaning
+ * apart by alignment, a name or an icon too.
+ *
+ * Compared with shadcn/ui: `class` replaces `className`, and every part has a `data-slot`.
+ *
+ * @param props - The bubble props: `variant`, `align`, `children` and the `div` attributes.
+ * @returns The bubble.
+ * @example
+ * ```tsx
+ * import { Bubble, BubbleContent } from "@/components/ui/bubble";
+ *
+ * export function Question() {
+ *   return (
+ *     <Bubble align="end" variant="muted">
+ *       <BubbleContent>How do I add a dialog?</BubbleContent>
+ *     </Bubble>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link BubbleContent}
+ * @see {@link BubbleReactions}
+ * @see {@link BubbleGroup}
+ */
+function Bubble(props: BubbleProps): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "variant", "align"]);
+  return (
+    <div
+      data-slot="bubble"
+      data-variant={local.variant ?? "default"}
+      data-align={local.align ?? "start"}
+      class={cn(bubbleVariants({ variant: local.variant, align: local.align }), local.class)}
+      {...rest}
+    />
+  );
+}
+
+/** The props as the implementation sees them. */
+type Loose = {
+  readonly as?: PolymorphicTarget;
+  readonly class?: ClassValue;
+  readonly [prop: string]: unknown;
+};
+
+/**
+ * Props of {@link BubbleContent}: every attribute of the chosen element. The `as` prop picks the element
+ * (a `div` by default); pass `"a"` or `"button"` to make the bubble a link or a button.
+ * @since 1.0.0
+ * @see {@link BubbleContent}
+ */
+export type BubbleContentProps<T extends PolymorphicTarget = "div"> = PolymorphicProps<
+  "div",
+  object,
+  T
+>;
+
+/**
+ * The text surface of a {@link Bubble}: the rounded, colored box that holds the message. It takes its
+ * colors from the bubble's `variant`. Render it as a link or a button with `as` for a bubble that does something.
+ *
+ * Keyboard and ARIA: no role of its own. A clickable bubble must be a real `button` or `a` (with `as`), so it takes
+ * focus and the native keys; a `div` with a click handler is not reachable by keyboard.
+ *
+ * @param props - The content props: `as`, `children` and the attributes of the element.
+ * @returns The content element.
+ * @example
+ * ```tsx
+ * import { Bubble, BubbleContent } from "@/components/ui/bubble";
+ *
+ * export function Suggestion() {
+ *   return (
+ *     <Bubble variant="outline">
+ *       <BubbleContent as="button" type="button">
+ *         Summarize this page
+ *       </BubbleContent>
+ *     </Bubble>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Bubble}
+ */
+function BubbleContent<T extends PolymorphicTarget = "div">(
+  props: BubbleContentProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as Loose, ["as", "class"]);
+  return (
+    <Polymorphic
+      as={local.as ?? "div"}
+      data-slot="bubble-content"
+      class={cn(
+        "min-w-0 rounded-2xl px-3.5 py-2 text-start text-sm leading-relaxed text-pretty break-words outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 [a&]:transition-colors [button&]:transition-colors motion-reduce:transition-none focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-transparent",
+        "group-data-[variant=default]/bubble:bg-primary group-data-[variant=default]/bubble:text-primary-foreground [a&]:group-data-[variant=default]/bubble:hover:bg-primary/90 [button&]:group-data-[variant=default]/bubble:hover:bg-primary/90",
+        "group-data-[variant=secondary]/bubble:bg-secondary group-data-[variant=secondary]/bubble:text-secondary-foreground",
+        "group-data-[variant=muted]/bubble:bg-muted group-data-[variant=muted]/bubble:text-foreground",
+        "group-data-[variant=tinted]/bubble:bg-primary/10 group-data-[variant=tinted]/bubble:text-foreground",
+        "group-data-[variant=outline]/bubble:border group-data-[variant=outline]/bubble:bg-background group-data-[variant=outline]/bubble:text-foreground [a&]:group-data-[variant=outline]/bubble:hover:bg-accent [button&]:group-data-[variant=outline]/bubble:hover:bg-accent",
+        "group-data-[variant=ghost]/bubble:rounded-none group-data-[variant=ghost]/bubble:px-0 group-data-[variant=ghost]/bubble:py-0 group-data-[variant=ghost]/bubble:text-foreground",
+        "group-data-[variant=destructive]/bubble:bg-destructive/10 group-data-[variant=destructive]/bubble:text-destructive",
+        "forced-colors:border forced-colors:border-[CanvasText]",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+const reactionsVariants = cva(
+  "absolute z-10 flex items-center gap-0.5 rounded-full border bg-background px-1.5 py-0.5 text-xs text-foreground shadow-xs [&_svg:not([class*='size-'])]:size-3.5",
+  {
+    variants: {
+      side: { top: "-top-3", bottom: "-bottom-3" },
+      align: { start: "start-3", end: "end-3" },
+    },
+    defaultVariants: { side: "bottom", align: "end" },
+  },
+);
+
+/**
+ * Props of {@link BubbleReactions}: the attributes of a `div` plus `side` (`"top"` or `"bottom"`, the
+ * default) and `align` (`"start"` or `"end"`, the default).
+ * @since 1.0.0
+ * @see {@link BubbleReactions}
+ */
+export type BubbleReactionsProps = ComponentProps<"div"> & VariantProps<typeof reactionsVariants>;
+
+/**
+ * A row of reactions that overlaps an edge of the bubble. Group them with `role="img"` and a descriptive
+ * `aria-label` ("2 people liked this") when they are only a summary, or make each one a real button with a
+ * label when they can be pressed. The bubble gains room under it for the overlap.
+ *
+ * Keyboard and ARIA: no role and no keys of its own; the buttons inside keep theirs.
+ *
+ * @param props - The reactions props: `side`, `align` and the `div` attributes.
+ * @returns The reactions row.
+ * @example
+ * ```tsx
+ * import { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble";
+ *
+ * export function Liked() {
+ *   return (
+ *     <Bubble variant="muted">
+ *       <BubbleContent>Shipped!</BubbleContent>
+ *       <BubbleReactions role="img" aria-label="2 people liked this">
+ *         <span aria-hidden="true">👍 2</span>
+ *       </BubbleReactions>
+ *     </Bubble>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Bubble}
+ */
+function BubbleReactions(props: BubbleReactionsProps): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "side", "align"]);
+  return (
+    <div
+      data-slot="bubble-reactions"
+      data-side={local.side ?? "bottom"}
+      data-align={local.align ?? "end"}
+      class={cn(reactionsVariants({ side: local.side, align: local.align }), local.class)}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Stacks consecutive bubbles from one sender with a small gap between them.
+ *
+ * Keyboard and ARIA: a plain `div`; it has no role and no keys.
+ *
+ * @param props - The `div` attributes and `class`.
+ * @returns The group.
+ * @example
+ * ```tsx
+ * import { Bubble, BubbleContent, BubbleGroup } from "@/components/ui/bubble";
+ *
+ * export function Burst() {
+ *   return (
+ *     <BubbleGroup>
+ *       <Bubble variant="muted">
+ *         <BubbleContent>First</BubbleContent>
+ *       </Bubble>
+ *       <Bubble variant="muted">
+ *         <BubbleContent>Second</BubbleContent>
+ *       </Bubble>
+ *     </BubbleGroup>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Bubble}
+ */
+function BubbleGroup(props: ComponentProps<"div">): JSX.Element {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <div data-slot="bubble-group" class={cn("flex w-full flex-col gap-1", local.class)} {...rest} />
+  );
+}
+
+export { Bubble, BubbleContent, BubbleGroup, BubbleReactions, bubbleVariants };

package/registry/bubble/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Bubble",
+  "description": "A framed message bubble for chat text, short structured output, quoted replies, suggestions and reactions."
+}