@ui-organized/svelte 0.0.0-stage → 6.0.0

package/dist/components/Breadcrumb/Breadcrumb.svelte

@@ -0,0 +1,58 @@
+<!--
+  A trail of links showing the current page's location in a hierarchy.
+
+  No Ark machine behind it — Ark UI has no Breadcrumb primitive — so the markup
+  here is the contract, compared element for element against the React library by
+  the parity gate.
+-->
+<script lang="ts">
+  import { clsx } from "clsx";
+  import Icon from "../Icon/Icon.svelte";
+  import type { BreadcrumbItem, BreadcrumbProps } from "./Breadcrumb.types.js";
+  import "@ui-organized/core/components/Breadcrumb/Breadcrumb.css";
+  import { glyph } from "../../icons/glyph.js";
+
+  const ICON_SIZE = 16;
+
+  let { items, separator, class: className, ...rest }: BreadcrumbProps = $props();
+
+  const isLast = (index: number) => index === items.length - 1;
+</script>
+
+{#snippet crumb(item: BreadcrumbItem)}
+  {#if item.icon}
+    <Icon name={item.icon} size={ICON_SIZE} class="breadcrumb__icon" />
+  {/if}
+  {#if typeof item.label === "string"}{item.label}{:else}{@render item.label()}{/if}
+{/snippet}
+
+<nav
+  aria-label="Breadcrumb"
+  class={clsx("breadcrumb", "text-default-body-medium", className)}
+  {...rest}
+>
+  <ol class="breadcrumb__list">
+    {#each items as item, index (index)}
+      <li class="breadcrumb__item">
+        {#if item.href && !isLast(index)}
+          <a href={item.href} class="breadcrumb__link">{@render crumb(item)}</a>
+        {:else}
+          <!--
+            The last crumb is the current page even when it carries an href, so it
+            renders as text rather than as a link nobody would follow.
+          -->
+          <span class="breadcrumb__current" aria-current={isLast(index) ? "page" : undefined}>
+            {@render crumb(item)}
+          </span>
+        {/if}
+        {#if !isLast(index)}
+          <span class="breadcrumb__separator" aria-hidden="true">
+            {#if separator == null}
+              <Icon name={glyph("chevron-right")} size={ICON_SIZE} />
+            {:else if typeof separator === "string"}{separator}{:else}{@render separator()}{/if}
+          </span>
+        {/if}
+      </li>
+    {/each}
+  </ol>
+</nav>

package/dist/components/Breadcrumb/Breadcrumb.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { BreadcrumbProps } from "./Breadcrumb.types.js";
+import "@ui-organized/core/components/Breadcrumb/Breadcrumb.css";
+declare const Breadcrumb: import("svelte").Component<BreadcrumbProps, {}, "">;
+type Breadcrumb = ReturnType<typeof Breadcrumb>;
+export default Breadcrumb;
+//# sourceMappingURL=Breadcrumb.svelte.d.ts.map

package/dist/components/Breadcrumb/Breadcrumb.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Breadcrumb.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Breadcrumb/Breadcrumb.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,yDAAyD,CAAC;AAmDjE,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/Breadcrumb/Breadcrumb.types.d.ts

@@ -0,0 +1,24 @@
+import type { IconComponent, IconName } from "../Icon/Icon.types.js";
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+export interface BreadcrumbItem {
+    /**
+     * Visible label for the crumb.
+     *
+     * A string, or a snippet for anything richer — the same union `Progress` takes,
+     * and for the same reason: React's `ReactNode` has no Svelte equivalent.
+     */
+    label: string | Snippet;
+    /** Link target. Omit on the current (last) crumb. */
+    href?: string;
+    /** Optional leading icon. */
+    icon?: IconName | IconComponent;
+}
+export interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "class" | "children"> {
+    /** The crumb trail, ordered from root to current page. */
+    items: BreadcrumbItem[];
+    /** Custom separator between crumbs. Defaults to a chevron icon. */
+    separator?: string | Snippet;
+    class?: string;
+}
+//# sourceMappingURL=Breadcrumb.types.d.ts.map

package/dist/components/Breadcrumb/Breadcrumb.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Breadcrumb.types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Breadcrumb/Breadcrumb.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,IAAI,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC9F,0DAA0D;IAC1D,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/components/Breadcrumb/Breadcrumb.types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/Breadcrumb/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Breadcrumb } from "./Breadcrumb.svelte";
+export type { BreadcrumbProps, BreadcrumbItem } from "./Breadcrumb.types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Breadcrumb/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Breadcrumb/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/components/Breadcrumb/index.js

@@ -0,0 +1 @@
+export { default as Breadcrumb } from "./Breadcrumb.svelte";

package/dist/components/Button/Button.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+  import { clsx } from "clsx";
+  import { CONTROL_ICON_SIZE, CONTROL_TEXT_CLASS, buttonStyles } from "@ui-organized/core";
+  import Icon from "../Icon/Icon.svelte";
+  import type { ButtonProps } from "./Button.types.js";
+  import "@ui-organized/core/components/Button/Button.css";
+
+  let {
+    intent,
+    size = "md",
+    icon,
+    iconPosition = "left",
+    type = "button",
+    class: className,
+    children,
+    asChild,
+    ...rest
+  }: ButtonProps = $props();
+
+  // An icon with no label collapses to a square (see `.btn--icon-only`) whose
+  // side matches the labelled-button height for the size, so icon buttons line
+  // up with text buttons instead of rendering short and wide.
+  const isIconOnly = $derived(icon != null && children === undefined);
+
+  const buttonClass = $derived(
+    clsx(
+      CONTROL_TEXT_CLASS[size],
+      buttonStyles({ intent, size }),
+      isIconOnly && "btn--icon-only",
+      className,
+    ),
+  );
+
+  // `type` is deliberately absent: it is meaningful on <button> and meaningless
+  // (or wrong) on the <a> an asChild snippet most often renders.
+  const childProps = () => ({ ...rest, class: buttonClass });
+</script>
+
+{#snippet content()}
+  {#if icon && iconPosition === "left"}<Icon name={icon} size={CONTROL_ICON_SIZE[size]} />{/if}
+  {@render children?.()}
+  {#if icon && iconPosition === "right"}<Icon name={icon} size={CONTROL_ICON_SIZE[size]} />{/if}
+{/snippet}
+
+{#if asChild}
+  {@render asChild(childProps, content)}
+{:else}
+  <button {type} class={buttonClass} {...rest}>
+    {@render content()}
+  </button>
+{/if}

package/dist/components/Button/Button.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { ButtonProps } from "./Button.types.js";
+import "@ui-organized/core/components/Button/Button.css";
+declare const Button: import("svelte").Component<ButtonProps, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;
+//# sourceMappingURL=Button.svelte.d.ts.map

package/dist/components/Button/Button.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Button/Button.svelte.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,iDAAiD,CAAC;AAwDzD,QAAA,MAAM,MAAM,iDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/components/Button/Button.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Button.test.d.ts.map

package/dist/components/Button/Button.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.test.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Button/Button.test.ts"],"names":[],"mappings":""}

package/dist/components/Button/Button.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/svelte";
+import { buttonStyles, CONTROL_TEXT_CLASS } from "@ui-organized/core";
+import Button from "./Button.svelte";
+/**
+ * The class list is the contract.
+ *
+ * Every framework library renders different code but must produce the same
+ * classes, because there is exactly one stylesheet and it is shared. A Svelte
+ * Button that emits `btn--medium` instead of `btn--md` type-checks, renders, and
+ * is invisibly unstyled. These assertions are deliberately written against
+ * literal strings as well as the recipe: comparing only to `buttonStyles()`
+ * would pass even if the recipe itself drifted.
+ */
+describe("Button", () => {
+    it("renders a native button with the default variant classes", () => {
+        const { container } = render(Button, { props: {} });
+        const button = container.querySelector("button");
+        expect(button).toBeTruthy();
+        expect(button.getAttribute("type")).toBe("button");
+        expect([...button.classList].sort()).toEqual(["btn", "btn--primary", "btn--md", "text-default-body-large"].sort());
+    });
+    it("agrees with the shared recipe for every intent and size", () => {
+        const intents = ["primary", "secondary", "tertiary", "ghost", "destructive", "destructive-ghost"];
+        const sizes = ["sm", "md", "lg"];
+        for (const intent of intents) {
+            for (const size of sizes) {
+                const { container, unmount } = render(Button, { props: { intent, size } });
+                const actual = [...container.querySelector("button").classList].sort();
+                const expected = [
+                    ...new Set(`${CONTROL_TEXT_CLASS[size]} ${buttonStyles({ intent, size })}`.split(/\s+/)),
+                ].sort();
+                expect(actual, `${intent}/${size}`).toEqual(expected);
+                unmount();
+            }
+        }
+    });
+    it("defaults type to button so it cannot submit a form by accident", () => {
+        const { container } = render(Button, { props: {} });
+        expect(container.querySelector("button").getAttribute("type")).toBe("button");
+    });
+    it("passes through arbitrary attributes and merges the caller's class", () => {
+        const { container } = render(Button, {
+            props: { class: "mine", disabled: true, "aria-label": "Save" },
+        });
+        const button = container.querySelector("button");
+        expect(button.classList.contains("mine")).toBe(true);
+        expect(button.classList.contains("btn")).toBe(true);
+        expect(button.hasAttribute("disabled")).toBe(true);
+        expect(button.getAttribute("aria-label")).toBe("Save");
+    });
+});

package/dist/components/Button/Button.types.d.ts

@@ -0,0 +1,53 @@
+import type { IconName } from "../Icon/Icon.types.js";
+import type { HTMLButtonAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { ControlSize } from "@ui-organized/core";
+import type { IconComponent } from "../../icons/registry.js";
+/**
+ * The props a polymorphic `asChild` snippet receives, as a function so the
+ * consumer spreads them at the point of use. This is Ark UI's own convention —
+ * matching it means a ui-organized Button composes with an Ark trigger exactly
+ * the way an Ark part does.
+ */
+export type ButtonPropsFn = () => Record<string, unknown>;
+export interface ButtonProps extends Omit<HTMLButtonAttributes, "class"> {
+    /**
+     * Visual style intent. Defaults to 'primary'.
+     *
+     * Spelled out rather than taken from cva's `ButtonVariants`, which widens
+     * every variant with `null` — a value the recipe accepts but the component's
+     * API should not.
+     */
+    intent?: "primary" | "secondary" | "tertiary" | "ghost" | "destructive" | "destructive-ghost";
+    /** Size variant. Defaults to 'md'. */
+    size?: ControlSize;
+    /** Icon rendered alongside the label; its native name in the active library, or a component. */
+    icon?: IconName | IconComponent;
+    /** Which side of the label the icon sits on. @default "left" */
+    iconPosition?: "left" | "right";
+    /** @default "button" — so a button inside a form does not submit by accident. */
+    type?: HTMLButtonAttributes["type"];
+    class?: string;
+    children?: Snippet;
+    /**
+     * Render something else as the button — an anchor, a router link — combining
+     * its props and behaviour. Ark UI has no Button primitive, so this is what
+     * makes a CTA a real, crawlable link while staying the library Button.
+     *
+     * Receives the props to spread *and* the button's own content, because the
+     * content is not just `children`: it is the icon and the label in the order
+     * `iconPosition` asks for. Ark's own `asChild` passes props alone, which is
+     * right for its parts — they have no content of their own to contribute.
+     * Dropping the second argument here would silently lose the icon.
+     *
+     * ```svelte
+     * <Button intent="primary">
+     *   {#snippet asChild(props, content)}
+     *     <a href="/pricing" {...props()}>{@render content()}</a>
+     *   {/snippet}
+     * </Button>
+     * ```
+     */
+    asChild?: Snippet<[ButtonPropsFn, Snippet]>;
+}
+//# sourceMappingURL=Button.types.d.ts.map

package/dist/components/Button/Button.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Button/Button.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACtE;;;;;;OAMG;IACH,MAAM,CAAC,EACH,SAAS,GACT,WAAW,GACX,UAAU,GACV,OAAO,GACP,aAAa,GACb,mBAAmB,CAAC;IACxB,sCAAsC;IACtC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gGAAgG;IAChG,IAAI,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IAChC,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,iFAAiF;IACjF,IAAI,CAAC,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C"}

package/dist/components/Button/Button.types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/Button/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Button } from "./Button.svelte";
+export type { ButtonProps, ButtonPropsFn } from "./Button.types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Button/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Button/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/components/Button/index.js

@@ -0,0 +1 @@
+export { default as Button } from "./Button.svelte";

package/dist/components/Calendar/Calendar.svelte

@@ -0,0 +1,334 @@
+<!--
+  The design-system calendar grid, shared by the date fields' popover.
+
+  Internal: it is not exported from the package barrel and has no parity case,
+  because it has no public DOM contract of its own — every pixel of it reaches a
+  user through DateInput, DateTimeInput or DateRangeInput.
+-->
+<script lang="ts">
+  import { tick } from "svelte";
+  import {
+    addDays,
+    addMonths,
+    clampYMD,
+    compareYMD,
+    isSameMonth,
+    isSameYMD,
+    isWithin,
+    monthGrid,
+    monthLabel,
+    monthName,
+    startOfMonth,
+    todayYMD,
+    toISODate,
+    weekdayLabels,
+    ymdToDate,
+    type YMD,
+  } from "@ui-organized/core";
+  import Button from "../Button/Button.svelte";
+  import Select from "../Select/Select.svelte";
+  import type { CalendarProps } from "./Calendar.types.js";
+  import "@ui-organized/core/components/Calendar/Calendar.css";
+  import { glyph } from "../../icons/glyph.js";
+
+  let {
+    mode,
+    value = null,
+    rangeValue,
+    min = null,
+    max = null,
+    numMonths = 1,
+    weekStartsOn = 0,
+    onSelect,
+    onRangeChange,
+    onRangeComplete,
+    onActiveDay,
+  }: CalendarProps = $props();
+
+  const today = todayYMD();
+  const start = $derived(rangeValue?.start ?? null);
+  const end = $derived(rangeValue?.end ?? null);
+
+  // Read once, at initialisation: this is where the calendar *opens*, not where
+  // it stays. Making it reactive would drag the view back to the selected month
+  // every time the value changed under a user who had paged away — so the
+  // one-shot read the compiler warns about is the whole point.
+  // svelte-ignore state_referenced_locally
+  const initialAnchor =
+    (mode === "single" ? value : (rangeValue?.start ?? null)) ?? clampYMD(today, min, max);
+
+  let viewMonth = $state<YMD>(startOfMonth(initialAnchor));
+  let focused = $state<YMD>(initialAnchor);
+  let hover = $state<YMD | null>(null);
+  // Portal the year Select's popup into the calendar's own subtree so option
+  // clicks aren't seen as an outside-interaction that dismisses the enclosing
+  // date popover (and so the popup inherits any theme scoped to that subtree).
+  let rootEl = $state<HTMLDivElement | null>(null);
+
+  // Roving focus: only move DOM focus when navigation came from the keyboard,
+  // never on hover/render, so opening the popup doesn't yank focus around.
+  // React needs an effect plus a "was this the keyboard?" flag, because its
+  // `setFocused` is shared with the click and focus handlers; awaiting the
+  // update inside `moveFocus` — the only keyboard path — says the same thing
+  // without the extra state.
+  const dayRefs = new Map<string, HTMLButtonElement>();
+
+  /**
+   * Registers a day button so keyboard navigation can focus it, and reports the
+   * roving-focus one to the caller. React does both from a ref callback; an
+   * action is the same hook — it runs after the node is in the DOM and again
+   * whenever the parameters change.
+   */
+  function dayRef(node: HTMLButtonElement, params: { iso: string; active: boolean }) {
+    dayRefs.set(params.iso, node);
+    if (params.active) onActiveDay?.(node);
+    return {
+      update(next: { iso: string; active: boolean }) {
+        if (next.iso !== params.iso) {
+          dayRefs.delete(params.iso);
+          dayRefs.set(next.iso, node);
+        }
+        params = next;
+        if (next.active) onActiveDay?.(node);
+      },
+      destroy() {
+        dayRefs.delete(params.iso);
+      },
+    };
+  }
+
+  function orderedPair(a: YMD, b: YMD): [YMD, YMD] {
+    return compareYMD(a, b) <= 0 ? [a, b] : [b, a];
+  }
+
+  /** `monthGrid`'s flat run of days, split into the weeks it already represents. */
+  function weeksOf(cells: YMD[]): YMD[][] {
+    const weeks: YMD[][] = [];
+    for (let i = 0; i < cells.length; i += 7) weeks.push(cells.slice(i, i + 7));
+    return weeks;
+  }
+
+  function ensureVisible(d: YMD) {
+    const lastVisible = addMonths(viewMonth, numMonths - 1);
+    if (compareYMD(d, viewMonth) < 0) {
+      viewMonth = startOfMonth(d);
+    } else if (compareYMD(d, { ...lastVisible, day: 31 }) > 0) {
+      viewMonth = startOfMonth(addMonths(d, -(numMonths - 1)));
+    }
+  }
+
+  async function moveFocus(next: YMD) {
+    focused = next;
+    // A keyed month can page here, remounting every button, so the node has to
+    // be looked up after the DOM has caught up rather than before.
+    ensureVisible(next);
+    await tick();
+    dayRefs.get(toISODate(next))?.focus();
+  }
+
+  function selectDay(day: YMD) {
+    if (!isWithin(day, min, max)) return;
+    if (mode === "single") {
+      onSelect?.(day);
+      return;
+    }
+    if (!start || (start && end) || compareYMD(day, start) < 0) {
+      onRangeChange?.({ start: day, end: null });
+    } else {
+      onRangeChange?.({ start, end: day });
+      onRangeComplete?.();
+    }
+  }
+
+  function onGridKeyDown(event: KeyboardEvent) {
+    const weekday = (ymdToDate(focused).getDay() - weekStartsOn + 7) % 7;
+    let next: YMD | null = null;
+    switch (event.key) {
+      case "ArrowLeft": next = addDays(focused, -1); break;
+      case "ArrowRight": next = addDays(focused, 1); break;
+      case "ArrowUp": next = addDays(focused, -7); break;
+      case "ArrowDown": next = addDays(focused, 7); break;
+      case "Home": next = addDays(focused, -weekday); break;
+      case "End": next = addDays(focused, 6 - weekday); break;
+      case "PageUp": next = addMonths(focused, -1); break;
+      case "PageDown": next = addMonths(focused, 1); break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        selectDay(focused);
+        return;
+      default:
+        return;
+    }
+    if (next) {
+      event.preventDefault();
+      moveFocus(clampYMD(next, min, max));
+    }
+  }
+
+  // Resolve the active range endpoints (committed range, or start↔hover preview)
+  // into ordered lo/hi so the in-range band renders the same either way.
+  const band = $derived.by((): { lo: YMD | null; hi: YMD | null } => {
+    if (mode !== "range" || !start) return { lo: null, hi: null };
+    const other = end ?? hover;
+    if (!other) return { lo: null, hi: null };
+    const [lo, hi] = orderedPair(start, other);
+    return { lo, hi };
+  });
+
+  const weekdays = $derived(weekdayLabels(weekStartsOn));
+  const months = $derived(
+    Array.from({ length: numMonths }, (_, i) => addMonths(viewMonth, i)),
+  );
+  const lastVisible = $derived(addMonths(viewMonth, numMonths - 1));
+
+  // Can't page earlier than the month containing `min`, nor later than `max`.
+  const prevDisabled = $derived(min ? compareYMD(viewMonth, startOfMonth(min)) <= 0 : false);
+  const nextDisabled = $derived(
+    max ? compareYMD(startOfMonth(lastVisible), startOfMonth(max)) >= 0 : false,
+  );
+
+  // Year dropdown options: bounded by min/max when set, else a wide default
+  // window, always widened to include every visible year.
+  const years = $derived.by(() => {
+    const baseYear = today.year;
+    const loYear = Math.min(min ? min.year : baseYear - 100, viewMonth.year);
+    const hiYear = Math.max(max ? max.year : baseYear + 10, lastVisible.year);
+    const out: number[] = [];
+    for (let y = loYear; y <= hiYear; y++) out.push(y);
+    return out;
+  });
+  const yearOptions = $derived(years.map((y) => ({ value: String(y), label: String(y) })));
+
+  function handleYearChange(monthIndex: number, newYear: number) {
+    const targetMonth = addMonths(viewMonth, monthIndex).month;
+    const newView = addMonths({ year: newYear, month: targetMonth, day: 1 }, -monthIndex);
+    viewMonth = newView;
+    focused = clampYMD(startOfMonth(newView), min, max);
+  }
+</script>
+
+{#snippet renderMonth(monthAnchor: YMD)}
+  <div class="calendar__month">
+    <div class="calendar__weekdays" aria-hidden="true">
+      {#each weekdays as w, i (i)}
+        <span class="calendar__weekday text-default-body-small">{w}</span>
+      {/each}
+    </div>
+    <!--
+      Weeks are real rows. A grid may only own rows, and a gridcell may only sit
+      in one — a flat run of 42 day buttons under role="grid" is neither.
+      `monthGrid` always returns six whole weeks, so the chunking is exact.
+    -->
+    <!--
+      The grid itself is not a tab stop: focus lives on the day buttons, one of
+      which always carries tabindex=0 (roving focus). A tabindex here would add a
+      second stop that lands on nothing.
+    -->
+    <!-- svelte-ignore a11y_interactive_supports_focus -->
+    <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+    <div
+      class="calendar__grid"
+      role="grid"
+      aria-label={monthLabel(monthAnchor.year, monthAnchor.month)}
+      onkeydown={onGridKeyDown}
+    >
+      {#each weeksOf(monthGrid(monthAnchor.year, monthAnchor.month, weekStartsOn)) as week (toISODate(week[0]!))}
+        <div class="calendar__week" role="row">
+          {#each week as d (toISODate(d))}
+            {@const iso = toISODate(d)}
+            {@const isSingleSel = mode === "single" && isSameYMD(d, value ?? null)}
+            {@const isLo = !!band.lo && isSameYMD(d, band.lo)}
+            {@const isHi = !!band.hi && isSameYMD(d, band.hi)}
+            {@const isEndpoint =
+              mode === "range" && (isSameYMD(d, start) || isSameYMD(d, end) || isLo || isHi)}
+            {@const selected = isSingleSel || isEndpoint}
+            <button
+              type="button"
+              class="calendar__day"
+              role="gridcell"
+              use:dayRef={{ iso, active: isSameYMD(d, focused) }}
+              tabindex={isSameYMD(d, focused) ? 0 : -1}
+              disabled={!isWithin(d, min, max)}
+              aria-label={ymdToDate(d).toLocaleDateString(undefined, {
+                weekday: "long",
+                year: "numeric",
+                month: "long",
+                day: "numeric",
+              })}
+              aria-selected={selected || undefined}
+              aria-current={isSameYMD(d, today) ? "date" : undefined}
+              data-outside={!isSameMonth(d, monthAnchor) || undefined}
+              data-today={isSameYMD(d, today) || undefined}
+              data-selected={selected || undefined}
+              data-range-lo={(isLo && band.hi && !isSameYMD(band.lo, band.hi)) || undefined}
+              data-range-hi={(isHi && band.lo && !isSameYMD(band.lo, band.hi)) || undefined}
+              data-in-range={(!!band.lo &&
+                !!band.hi &&
+                compareYMD(d, band.lo) > 0 &&
+                compareYMD(d, band.hi) < 0) ||
+                undefined}
+              onclick={() => {
+                focused = d;
+                selectDay(d);
+              }}
+              onmouseenter={() => {
+                if (mode === "range" && start && !end) hover = d;
+              }}
+              onfocus={() => (focused = d)}
+            >
+              <span class="calendar__day-label text-default-body-large">{d.day}</span>
+            </button>
+          {/each}
+        </div>
+      {/each}
+    </div>
+  </div>
+{/snippet}
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="calendar" bind:this={rootEl} onmouseleave={() => (hover = null)}>
+  <div class="calendar__header">
+    <Button
+      intent="ghost"
+      size="sm"
+      icon={glyph("chevron-left")}
+      class="calendar__nav"
+      onclick={() => (viewMonth = addMonths(viewMonth, -1))}
+      disabled={prevDisabled}
+      aria-label="Previous month"
+    />
+    <div class="calendar__labels">
+      {#each months as m, i (`${m.year}-${m.month}`)}
+        <div class="calendar__label">
+          <span class="calendar__month-name text-emphasis-body-large">
+            {monthName(m.year, m.month)}
+          </span>
+          <Select
+            variant="ghost"
+            size="sm"
+            label={`Year, ${monthName(m.year, m.month)}`}
+            options={yearOptions}
+            value={String(m.year)}
+            onValueChange={(v) => handleYearChange(i, Number(v))}
+            portalContainer={rootEl}
+          />
+        </div>
+      {/each}
+    </div>
+    <Button
+      intent="ghost"
+      size="sm"
+      icon={glyph("chevron-right")}
+      class="calendar__nav"
+      onclick={() => (viewMonth = addMonths(viewMonth, 1))}
+      disabled={nextDisabled}
+      aria-label="Next month"
+    />
+  </div>
+  <div class="calendar__months">
+    {#each months as m (`${m.year}-${m.month}`)}
+      {@render renderMonth(m)}
+    {/each}
+  </div>
+</div>

package/dist/components/Calendar/Calendar.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { CalendarProps } from "./Calendar.types.js";
+import "@ui-organized/core/components/Calendar/Calendar.css";
+declare const Calendar: import("svelte").Component<CalendarProps, {}, "">;
+type Calendar = ReturnType<typeof Calendar>;
+export default Calendar;
+//# sourceMappingURL=Calendar.svelte.d.ts.map

package/dist/components/Calendar/Calendar.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Calendar.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/components/Calendar/Calendar.svelte.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,qDAAqD,CAAC;AAqQ7D,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/components/Calendar/Calendar.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Calendar.test.d.ts.map