@shadow-js/ui 0.0.0-stage → 1.0.0

package/registry/button/button.tsx

@@ -0,0 +1,125 @@
+import { splitProps } from "@shadow-js/core";
+import { Polymorphic, type PolymorphicProps, type PolymorphicTarget } from "@shadow-js/primitives";
+import type { 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 button for each `variant` and `size`. Use it to style a link or any other
+ * element like a button.
+ *
+ * @example
+ * ```tsx
+ * import { buttonVariants } from "@/components/ui/button";
+ *
+ * export function DocsLink() {
+ *   return (
+ *     <a class={buttonVariants({ variant: "outline", size: "sm" })} href="/docs">
+ *       Docs
+ *     </a>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Button}
+ */
+const buttonVariants = cva(
+  "inline-flex shrink-0 items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 forced-colors:disabled:opacity-100 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-transparent",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+        secondary: "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        xs: "h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+        "icon-xs": "size-6 rounded-md [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm": "size-8",
+        "icon-lg": "size-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+/** The props as the implementation sees them: the typed own props plus whatever the target takes. */
+type Loose = VariantProps<typeof buttonVariants> & {
+  readonly as?: PolymorphicTarget;
+  readonly class?: ClassValue;
+  readonly [prop: string]: unknown;
+};
+
+/**
+ * Props of {@link Button}: every attribute of the chosen element plus `variant` and `size`. The
+ * `variant` is `"default"` (the default), `"destructive"`, `"outline"`, `"secondary"`, `"ghost"` or
+ * `"link"`. The `size` is `"default"` (the default), `"xs"`, `"sm"`, `"lg"`, `"icon"`, `"icon-xs"`,
+ * `"icon-sm"` or `"icon-lg"`. The `as` prop picks the element (a `button` by default).
+ * @since 1.0.0
+ * @see {@link Button}
+ */
+export type ButtonProps<T extends PolymorphicTarget = "button"> = PolymorphicProps<
+  "button",
+  VariantProps<typeof buttonVariants>,
+  T
+>;
+
+/**
+ * A button. Pick the look with `variant` and the height with `size`. Use `as` to render another
+ * element, for example a link: `<Button as="a" href="/docs">Docs</Button>`.
+ *
+ * Keyboard and ARIA: the default element is a native `button`, so Enter and Space activate it and
+ * it takes focus with Tab. `disabled` is forwarded to the element, which then ignores clicks. The
+ * button's accessible name is its text, so an icon-only button (`size="icon"`) needs an
+ * `aria-label`. The component adds no ARIA attributes of its own.
+ *
+ * Compared with shadcn/ui: `as` replaces `asChild`, `class` replaces `className`, and the element
+ * carries `data-slot="button"`. The props are typed from `@shadow-js/primitives`.
+ *
+ * @param props - The button props: `variant`, `size`, `as`, `children`, and the attributes of the
+ * element (for example `onClick` and `disabled`).
+ * @returns The button element.
+ * @example
+ * ```tsx
+ * import { Button } from "@/components/ui/button";
+ *
+ * export function SaveButton() {
+ *   const save = (): void => {
+ *     console.log("saved");
+ *   };
+ *   return (
+ *     <Button variant="outline" size="sm" onClick={save}>
+ *       Save
+ *     </Button>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link ButtonProps}
+ * @see {@link buttonVariants}
+ */
+function Button<T extends PolymorphicTarget = "button">(props: ButtonProps<T>): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as Loose, ["as", "class", "variant", "size"]);
+  return (
+    <Polymorphic
+      as={local.as ?? "button"}
+      data-slot="button"
+      class={cn(buttonVariants({ variant: local.variant, size: local.size }), local.class)}
+      {...rest}
+    />
+  );
+}
+
+export { Button, buttonVariants };

package/registry/button/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Button",
+  "description": "Displays a button or a component that looks like a button."
+}

package/registry/button-group/button-group.tsx

@@ -0,0 +1,189 @@
+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";
+
+const groupVariants = cva(
+  "flex w-fit items-stretch [&>*]:focus-visible:relative [&>*]:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2",
+  {
+    variants: {
+      orientation: {
+        horizontal:
+          "[&>*:not(:first-child)]:rounded-s-none [&>*:not(:first-child)]:border-s-0 [&>*:not(:last-child)]:rounded-e-none",
+        vertical:
+          "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none",
+      },
+    },
+    defaultVariants: { orientation: "horizontal" },
+  },
+);
+
+/**
+ * Props of {@link ButtonGroup}: the attributes of a `div` plus `orientation`. The `orientation` is
+ * `"horizontal"` (the default) or `"vertical"`.
+ * @since 1.0.0
+ * @see {@link ButtonGroup}
+ */
+export type ButtonGroupProps = ComponentProps<"div"> & VariantProps<typeof groupVariants>;
+
+/**
+ * Buttons (or inputs) that sit together as one control: the inner corners are square and the
+ * borders meet. Horizontal by default; `orientation="vertical"` stacks them.
+ *
+ * Keyboard and ARIA: the group is a `div` with `role="group"`. It adds no keys, so each button
+ * keeps its own keys (Tab moves between them). Give the group an `aria-label` that names the
+ * controls, because a group without a name is announced without one. A focused child is raised
+ * above its neighbors so its focus ring shows.
+ *
+ * Compared with shadcn/ui: `class` replaces `className`, and the element carries
+ * `data-slot="button-group"`.
+ *
+ * @param props - The group props: `orientation`, `children`, and the `div` attributes.
+ * @returns The group element.
+ * @example
+ * ```tsx
+ * import { Button } from "@/components/ui/button";
+ * import { ButtonGroup } from "@/components/ui/button-group";
+ *
+ * export function Alignment() {
+ *   return (
+ *     <ButtonGroup aria-label="Text alignment">
+ *       <Button variant="outline">Left</Button>
+ *       <Button variant="outline">Center</Button>
+ *       <Button variant="outline">Right</Button>
+ *     </ButtonGroup>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link ButtonGroupProps}
+ * @see {@link ButtonGroupSeparator}
+ * @see {@link ButtonGroupText}
+ */
+function ButtonGroup(props: ButtonGroupProps): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "orientation"]);
+  return (
+    <div
+      role="group"
+      data-slot="button-group"
+      data-orientation={local.orientation ?? "horizontal"}
+      class={cn(groupVariants({ orientation: local.orientation }), local.class)}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * A divider between two buttons of a group. It is a vertical separator by default, so assistive
+ * technology announces it as a separator; `orientation="horizontal"` draws a line between the
+ * buttons of a vertical group.
+ *
+ * Keyboard and ARIA: it has `role="separator"`, `aria-orientation` set to its orientation, and no
+ * keys.
+ *
+ * @param props - The separator props: `orientation` (`"vertical"` by default) and the `div`
+ * attributes.
+ * @returns The separator element.
+ * @example
+ * ```tsx
+ * import { Button } from "@/components/ui/button";
+ * import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group";
+ *
+ * export function Split() {
+ *   return (
+ *     <ButtonGroup aria-label="Save options">
+ *       <Button variant="outline">Save</Button>
+ *       <ButtonGroupSeparator />
+ *       <Button variant="outline">More</Button>
+ *     </ButtonGroup>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link ButtonGroup}
+ */
+function ButtonGroupSeparator(
+  props: ComponentProps<"div"> & { readonly orientation?: "horizontal" | "vertical" | undefined },
+): JSX.Element {
+  const [local, rest] = splitProps(props, ["class", "orientation"]);
+  const orientation = (): "horizontal" | "vertical" => local.orientation ?? "vertical";
+  return (
+    <div
+      role="separator"
+      aria-orientation={orientation()}
+      data-orientation={orientation()}
+      data-slot="button-group-separator"
+      class={cn(
+        "relative !m-0 bg-input",
+        orientation() === "horizontal" ? "h-px w-full" : "w-px self-stretch",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Props of {@link ButtonGroupText}: the attributes of the rendered element, and `as` to change it.
+ * @since 1.0.0
+ * @see {@link ButtonGroupText}
+ */
+export type ButtonGroupTextProps<T extends PolymorphicTarget = "div"> = PolymorphicProps<
+  "div",
+  object,
+  T
+>;
+
+/** The props as the implementation sees them: the typed own props plus whatever the target takes. */
+type TextLoose = {
+  /** The element to render instead of a `div`. */
+  readonly as?: PolymorphicTarget;
+  /** Classes added to the text's own classes (merged with tailwind-merge). */
+  readonly class?: ClassValue;
+  readonly [prop: string]: unknown;
+};
+
+/**
+ * Text inside a group, styled like a button without being one. Use it for a label such as "Sort
+ * by" next to the buttons. It has no role and no keys. `as` renders another element (a link or a
+ * label), where shadcn uses `render`.
+ *
+ * @param props - The text props: `as` (`"div"` by default), `children`, and the attributes of the
+ * rendered element.
+ * @returns The text element.
+ * @example
+ * ```tsx
+ * import { Button } from "@/components/ui/button";
+ * import { ButtonGroup, ButtonGroupText } from "@/components/ui/button-group";
+ *
+ * export function SortControl() {
+ *   return (
+ *     <ButtonGroup aria-label="Sort">
+ *       <ButtonGroupText>Sort by</ButtonGroupText>
+ *       <Button variant="outline">Date</Button>
+ *     </ButtonGroup>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link ButtonGroup}
+ */
+function ButtonGroupText<T extends PolymorphicTarget = "div">(
+  props: ButtonGroupTextProps<T>,
+): JSX.Element {
+  const [local, rest] = splitProps(props as unknown as TextLoose, ["as", "class"]);
+  return (
+    <Polymorphic
+      as={local.as ?? "div"}
+      data-slot="button-group-text"
+      class={cn(
+        "flex items-center gap-2 rounded-md border bg-muted px-4 text-sm font-medium shadow-xs [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        local.class,
+      )}
+      {...rest}
+    />
+  );
+}
+
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText };

package/registry/button-group/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Button Group",
+  "description": "Buttons and inputs that sit together as one control, with the inner corners square and the borders joined."
+}

package/registry/calendar/calendar.tsx

@@ -0,0 +1,348 @@
+import { splitProps } from "@shadow-js/core";
+import {
+  type CalendarDate,
+  Calendar as CalendarPrimitive,
+  type CalendarProps as CalendarPrimitiveProps,
+  type CalendarValue,
+  useCalendar,
+} from "@shadow-js/primitives";
+import type { JSX } from "@shadow-js/web";
+import { Button } from "@/components/ui/button";
+import { ChevronLeftIcon, ChevronRightIcon } from "@/components/ui/icons";
+import { useUiStrings } from "@/lib/ui-strings";
+import { cn } from "@/lib/utils";
+
+/**
+ * Props of {@link Calendar}: every prop of the primitive (`mode`, `value`, `onValueChange`, `min`,
+ * `max`, `disabled`, `locale`, `weekStartsOn`, `defaultMonth`, `today`, `dir`, `timeZone`), plus the props this
+ * component adds: `captionLayout`, `yearRange` and `labels`. With `captionLayout="dropdown"` a month
+ * select and a year select replace the caption.
+ * @since 1.0.0
+ * @see {@link Calendar}
+ */
+export type CalendarProps = CalendarPrimitiveProps & {
+  /**
+   * `"label"` shows the month name in the caption. `"dropdown"` shows a month select and a year
+   * select instead.
+   * @default "label"
+   */
+  readonly captionLayout?: "label" | "dropdown" | undefined;
+  /**
+   * How many years on either side of the shown year the year select lists.
+   * @default 10
+   */
+  readonly yearRange?: number | undefined;
+  /** The names of the controls, for a language other than English. See {@link CalendarLabels}. */
+  readonly labels?: CalendarLabels | undefined;
+};
+
+/**
+ * The names of the calendar's controls, for a language other than English. Each name is optional,
+ * and the English default is used for any name you leave out.
+ * @since 1.0.0
+ * @see {@link CalendarProps}
+ */
+export interface CalendarLabels {
+  /**
+   * The accessible name of the previous-month button.
+   * @default "Previous month"
+   */
+  readonly previousMonth?: string | undefined;
+  /**
+   * The accessible name of the next-month button.
+   * @default "Next month"
+   */
+  readonly nextMonth?: string | undefined;
+  /**
+   * The accessible name of the month select in the dropdown layout.
+   * @default "Month"
+   */
+  readonly month?: string | undefined;
+  /**
+   * The accessible name of the year select in the dropdown layout.
+   * @default "Year"
+   */
+  readonly year?: string | undefined;
+}
+
+/** The month names of a locale, from `Intl` (January first). @internal */
+function monthNames(locale: string): string[] {
+  const format = new Intl.DateTimeFormat(locale, { month: "long", timeZone: "UTC" });
+  return Array.from({ length: 12 }, (_, index) =>
+    format.format(new Date(Date.UTC(2000, index, 15))),
+  );
+}
+
+/** The previous and next month buttons and the caption (or the selects). @internal */
+function CalendarHeader(props: {
+  readonly layout: "label" | "dropdown";
+  readonly yearRange: number;
+  readonly labels: CalendarLabels | undefined;
+}): JSX.Element {
+  const calendar = useCalendar("Calendar");
+  const t = useUiStrings();
+  const shown = calendar.month;
+  const months = monthNames(calendar.locale);
+  const years = (): number[] => {
+    const center = shown().year;
+    return Array.from(
+      { length: props.yearRange * 2 + 1 },
+      (_, index) => center - props.yearRange + index,
+    );
+  };
+  const jumpTo = (year: number, month: number): void => {
+    const current = shown();
+    calendar.navigate((year - current.year) * 12 + (month - current.month));
+  };
+  return (
+    <div data-slot="calendar-header" class="relative flex items-center justify-center pt-1">
+      <Button
+        data-slot="calendar-previous"
+        variant="outline"
+        size="icon"
+        class="absolute start-1 size-7 bg-transparent p-0 opacity-50 hover:opacity-100"
+        aria-label={props.labels?.previousMonth ?? t("calendar.previousMonth", "Previous month")}
+        onClick={() => calendar.navigate(-1)}
+        disabled={!calendar.canGoPrevious()}
+      >
+        <ChevronLeftIcon class="rtl:-scale-x-100" />
+      </Button>
+      {props.layout === "dropdown" ? (
+        <div data-slot="calendar-dropdowns" class="flex items-center gap-1 text-sm font-medium">
+          <select
+            aria-label={props.labels?.month ?? t("calendar.month", "Month")}
+            data-slot="calendar-month-select"
+            class="h-7 rounded-md border border-input bg-transparent px-2 text-sm"
+            value={String(shown().month)}
+            onChange={(event: Event) =>
+              jumpTo(shown().year, Number((event.currentTarget as HTMLSelectElement).value))
+            }
+          >
+            {months.map((name, index) => (
+              <option value={index + 1}>{name}</option>
+            ))}
+          </select>
+          <select
+            aria-label={props.labels?.year ?? t("calendar.year", "Year")}
+            data-slot="calendar-year-select"
+            class="h-7 rounded-md border border-input bg-transparent px-2 text-sm"
+            value={String(shown().year)}
+            onChange={(event: Event) =>
+              jumpTo(Number((event.currentTarget as HTMLSelectElement).value), shown().month)
+            }
+          >
+            {years().map((year) => (
+              <option value={year}>{year}</option>
+            ))}
+          </select>
+          <div
+            id={calendar.captionId()}
+            aria-live="polite"
+            data-slot="calendar-caption"
+            class="sr-only"
+          >
+            {calendar.caption()}
+          </div>
+        </div>
+      ) : (
+        <div
+          id={calendar.captionId()}
+          aria-live="polite"
+          data-slot="calendar-caption"
+          class="text-sm font-medium"
+        >
+          {calendar.caption()}
+        </div>
+      )}
+      <Button
+        data-slot="calendar-next"
+        variant="outline"
+        size="icon"
+        class="absolute end-1 size-7 bg-transparent p-0 opacity-50 hover:opacity-100"
+        aria-label={props.labels?.nextMonth ?? t("calendar.nextMonth", "Next month")}
+        onClick={() => calendar.navigate(1)}
+        disabled={!calendar.canGoNext()}
+      >
+        <ChevronRightIcon class="rtl:-scale-x-100" />
+      </Button>
+    </div>
+  );
+}
+
+/** The weekday header and the weeks, as a grid. @internal */
+function CalendarGrid(): JSX.Element {
+  const calendar = useCalendar("Calendar");
+  return (
+    <table
+      // biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: a calendar grid is the WAI-ARIA grid pattern on a real table
+      role="grid"
+      data-slot="calendar-grid"
+      aria-labelledby={calendar.captionId()}
+      aria-multiselectable={calendar.mode === "single" ? undefined : true}
+      class="w-full border-collapse"
+    >
+      <thead>
+        <tr>
+          {calendar.weekdays().map((label) => (
+            <th
+              scope="col"
+              abbr={label.long}
+              class="w-8 rounded-md text-[0.8rem] font-normal text-muted-foreground"
+            >
+              {label.short}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {calendar.weeks().map((week) => (
+          <tr role="row" class="mt-2">
+            {week.map((day: CalendarDate) => (
+              <CalendarDayCell date={day} />
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+/**
+ * One day of the grid: the primitive's `gridcell` with this kit's look. It shows the day number and
+ * styles the selection, the range, today, the days of another month and the focus ring. It is used
+ * by {@link Calendar} for every day; use it directly only when you build your own grid.
+ *
+ * Keyboard and ARIA: the focused day is the only one in the tab order. Enter and Space select it,
+ * and the arrow keys, PageUp and PageDown, and Home and End move the focus. It carries
+ * `aria-selected`, `aria-disabled` and `aria-current="date"` for today.
+ *
+ * @param props - The day props: `date`, a `{ year, month, day }` value.
+ * @returns The day cell element.
+ * @example
+ * ```tsx
+ * import { CalendarDayCell } from "@/components/ui/calendar";
+ *
+ * export function March5() {
+ *   return <CalendarDayCell date={{ year: 2026, month: 3, day: 5 }} />;
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Calendar}
+ */
+function CalendarDayCell(props: { readonly date: CalendarDate }): JSX.Element {
+  return (
+    <CalendarPrimitive.Day
+      date={props.date}
+      data-slot="calendar-day"
+      class={cn(
+        "relative size-8 p-0 text-center text-sm select-none outline-none",
+        "[&>span]:flex [&>span]:size-8 [&>span]:items-center [&>span]:justify-center [&>span]:rounded-md [&>span]:font-normal",
+        "data-[outside]:text-muted-foreground data-[disabled]:opacity-50 data-[today]:bg-accent data-[today]:text-accent-foreground",
+        "data-[range=middle]:bg-accent data-[range=middle]:text-accent-foreground",
+        "data-[selected]:bg-primary data-[selected]:text-primary-foreground",
+        "focus-visible:z-10 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",
+        "forced-colors:data-[selected]:bg-[Highlight] forced-colors:data-[selected]:text-[HighlightText]",
+      )}
+    >
+      <span>{props.date.day}</span>
+    </CalendarPrimitive.Day>
+  );
+}
+
+/**
+ * A month of days to pick from: one day, several days, or a range (`mode`, default `"single"`).
+ * It has month navigation, or a month and a year select with `captionLayout="dropdown"`, and it
+ * follows the locale's names and week start. There is no date library: the dates are plain
+ * `{ year, month, day }` values.
+ *
+ * Keyboard and ARIA: the days form a `role="grid"`, named by the caption in the default label
+ * layout. Only the focused day is in the tab order. Left and Right move one day (swapped in
+ * right-to-left layouts), Up and Down move a week, PageUp and PageDown move a month (with Shift, a
+ * year), and Home and End move to the first and last day of the week. Enter and Space select the
+ * focused day. Each day is a `gridcell` with `aria-selected` and `aria-disabled`. The caption is
+ * `aria-live="polite"`, so a month change is announced. The previous and next buttons are named
+ * "Previous month" and "Next month" unless you pass `labels`. A `mode` other than `"single"` sets
+ * `aria-multiselectable` on the grid.
+ *
+ * Compared with shadcn/ui: the selection is `value` and `onValueChange` (not `selected` and
+ * `onSelect`), and the dates are plain `{ year, month, day }` objects, not `Date` values. `class`
+ * replaces `className`, and `labels` is a ShadowJS prop for the control names.
+ *
+ * @param props - The calendar props: see {@link CalendarProps}.
+ * @returns The calendar element.
+ * @example
+ * ```tsx
+ * import { Calendar } from "@/components/ui/calendar";
+ *
+ * export function Picker() {
+ *   return (
+ *     <Calendar
+ *       mode="range"
+ *       defaultMonth={{ year: 2026, month: 3 }}
+ *       captionLayout="dropdown"
+ *     />
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link CalendarProps}
+ * @see {@link CalendarDayCell}
+ * @see {@link isCalendarDay}
+ */
+function Calendar(props: CalendarProps): JSX.Element {
+  const [local, rest] = splitProps(props as CalendarProps & { readonly class?: unknown }, [
+    "class",
+    "captionLayout",
+    "yearRange",
+    "labels",
+  ]);
+  return (
+    <CalendarPrimitive
+      data-slot="calendar"
+      class={cn("group/calendar bg-background p-3", local.class as string | undefined)}
+      {...rest}
+    >
+      <CalendarHeader
+        layout={(local.captionLayout as "label" | "dropdown" | undefined) ?? "label"}
+        yearRange={(local.yearRange as number | undefined) ?? 10}
+        labels={local.labels as CalendarLabels | undefined}
+      />
+      <div class="mt-4">
+        <CalendarGrid />
+      </div>
+    </CalendarPrimitive>
+  );
+}
+
+/**
+ * Narrows a {@link CalendarValue} to a single day. Use it in `onValueChange` of a single-day
+ * calendar, where the value is one `{ year, month, day }` date.
+ *
+ * @param value - The selection to check.
+ * @returns `true` when `value` is one day, so it can be used as a {@link CalendarDate}.
+ * @example
+ * ```tsx
+ * import { useSignal } from "@shadow-js/core";
+ * import type { CalendarDate } from "@shadow-js/primitives";
+ * import { Calendar, isCalendarDay } from "@/components/ui/calendar";
+ *
+ * export function DatePick() {
+ *   const [date, setDate] = useSignal<CalendarDate | undefined>(undefined);
+ *   return (
+ *     <Calendar
+ *       value={date()}
+ *       onValueChange={(value) => {
+ *         if (isCalendarDay(value)) setDate(value);
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link Calendar}
+ */
+function isCalendarDay(value: CalendarValue): value is CalendarDate {
+  return typeof value === "object" && value !== null && "day" in value;
+}
+
+export { Calendar, CalendarDayCell, isCalendarDay };

package/registry/calendar/item.json

@@ -0,0 +1,4 @@
+{
+  "title": "Calendar",
+  "description": "A month grid to pick one day, several days or a range, with a keyboard grid, locale names and month and year navigation."
+}