@urbicon-ui/blocks 6.1.4

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

@@ -0,0 +1,43 @@
+import type { HTMLAttributes } from 'svelte/elements';
+/** Per-slot class overrides for {@link SparklineProps}. */
+export type SparklineSlotClasses = Partial<Record<'root' | 'svg' | 'line' | 'area' | 'point', string>>;
+/**
+ * @description Tiny inline trend line — no axes, no labels — sized to flow in
+ * table cells, cards, or running text. Zero-dependency SVG, optional area fill
+ * and end-point dot. Aria-hidden by default with an optional `ariaLabel`.
+ *
+ * @tag display
+ * @tag data
+ * @related LineChart
+ * @stability beta
+ *
+ * @example
+ * ```svelte
+ * <Sparkline data={[3, 5, 4, 8, 6, 9]} area />
+ * ```
+ */
+export interface SparklineProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+    /** Sequence of values plotted left → right. */
+    data: number[];
+    /** Width in px. @default 96 */
+    width?: number;
+    /** Height in px. @default 24 */
+    height?: number;
+    /** Fill the area under the line. @default false */
+    area?: boolean;
+    /** Mark the last point with a dot. @default false */
+    showEndPoint?: boolean;
+    /** Line + fill color. @default var(--color-chart-1) */
+    color?: string;
+    /** Stroke width in px. @default 1.5 */
+    strokeWidth?: number;
+    /** Accessible label; when omitted the sparkline is aria-hidden. */
+    ariaLabel?: string;
+    /** Extra classes merged onto the wrapper. */
+    class?: string;
+    /** Remove all default classes. */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: SparklineSlotClasses;
+}
+export { default as Sparkline } from './Sparkline.svelte';

package/dist/components/Sparkline/index.js

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

package/dist/components/ThemeSwitcher/ThemeSwitcher.svelte

@@ -0,0 +1,146 @@
+<script lang="ts">
+  import type { ThemeSwitcherProps, Theme } from './index';
+  import { themeSwitcherVariants } from './themeSwitcher.variants';
+  import { onMount } from 'svelte';
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { resolveIcon } from '../../icons';
+  import SunIconDefault from '../../icons/SunIcon.svelte';
+  import MoonIconDefault from '../../icons/MoonIcon.svelte';
+  import MonitorIconDefault from '../../icons/MonitorIcon.svelte';
+  import { useBlocksI18n } from '../../i18n';
+
+  const bt = useBlocksI18n();
+
+  const SunIcon = resolveIcon('sun', SunIconDefault);
+  const MoonIcon = resolveIcon('moon', MoonIconDefault);
+  const MonitorIcon = resolveIcon('monitor', MonitorIconDefault);
+
+  let {
+    theme = $bindable('system'),
+    strategy = 'cycle',
+    storageKey = 'urbicon-theme',
+    onThemeChange,
+    variant = 'ghost',
+    size = 'md',
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    disabled = false
+  }: ThemeSwitcherProps = $props();
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.ThemeSwitcher?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'ThemeSwitcher', preset),
+      slotClassesProp
+    )
+  );
+
+  let mounted = $state(false);
+
+  const styles = $derived(
+    unstyled ? undefined : themeSwitcherVariants({ variant, size, disabled })
+  );
+
+  function slot(name: 'button' | 'icon') {
+    const base = styles?.[name]?.() ?? '';
+    const override = slotClasses?.[name] ?? '';
+    return override ? `${base} ${override}` : base;
+  }
+
+  const resolvedTheme: Theme = $derived.by(() => {
+    if (theme !== 'system' || typeof window === 'undefined') return theme;
+    if (!mounted) return 'light';
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  });
+
+  const label = $derived(
+    theme === 'light'
+      ? bt('themeSwitcher.lightMode')
+      : theme === 'dark'
+        ? bt('themeSwitcher.darkMode')
+        : bt('themeSwitcher.systemTheme')
+  );
+
+  function setTheme(next: Theme) {
+    theme = next;
+    applyTheme();
+    onThemeChange?.(next);
+  }
+
+  function cycle() {
+    if (strategy === 'toggle') {
+      setTheme(resolvedTheme === 'light' ? 'dark' : 'light');
+    } else {
+      const next: Theme = theme === 'light' ? 'dark' : theme === 'dark' ? 'system' : 'light';
+      setTheme(next);
+    }
+  }
+
+  function applyTheme() {
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+
+    if (theme === 'light') {
+      root.classList.remove('dark');
+      root.classList.add('light');
+      if (storageKey) localStorage.setItem(storageKey, 'light');
+    } else if (theme === 'dark') {
+      root.classList.remove('light');
+      root.classList.add('dark');
+      if (storageKey) localStorage.setItem(storageKey, 'dark');
+    } else {
+      root.classList.remove('light', 'dark');
+      if (storageKey) localStorage.removeItem(storageKey);
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      root.classList.toggle('dark', prefersDark);
+    }
+  }
+
+  onMount(() => {
+    mounted = true;
+
+    if (storageKey) {
+      const saved = localStorage.getItem(storageKey);
+      if (saved === 'light' || saved === 'dark') {
+        theme = saved;
+      }
+    }
+    applyTheme();
+
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = () => {
+      if (theme === 'system') applyTheme();
+    };
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  });
+
+  export function getTheme(): Theme {
+    return theme;
+  }
+
+  export function getResolvedTheme(): Theme {
+    return resolvedTheme;
+  }
+</script>
+
+<button
+  type="button"
+  onclick={cycle}
+  class="{slot('button')} {className}"
+  aria-label={label}
+  title={label}
+  {disabled}
+>
+  {#if theme === 'light'}
+    <SunIcon class={slot('icon')} />
+  {:else if theme === 'dark'}
+    <MoonIcon class={slot('icon')} />
+  {:else}
+    <MonitorIcon class={slot('icon')} />
+  {/if}
+</button>

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

@@ -0,0 +1,7 @@
+import type { ThemeSwitcherProps, Theme } from './index';
+declare const ThemeSwitcher: import("svelte").Component<ThemeSwitcherProps, {
+    getTheme: () => Theme;
+    getResolvedTheme: () => Theme;
+}, "theme">;
+type ThemeSwitcher = ReturnType<typeof ThemeSwitcher>;
+export default ThemeSwitcher;

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

@@ -0,0 +1,57 @@
+import type { ThemeSwitcherVariants } from './themeSwitcher.variants';
+export type Theme = 'light' | 'dark' | 'system';
+/**
+ * Props for the ThemeSwitcher component.
+ *
+ * @description Cycles between light, dark, and system color schemes.
+ * Applies light/dark classes on the html element and persists to localStorage.
+ *
+ * @tag action
+ * @related LocaleSwitcher
+ *
+ * @example
+ * ```svelte
+ * <ThemeSwitcher />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <ThemeSwitcher size="lg" variant="outlined" strategy="toggle" />
+ * ```
+ */
+export interface ThemeSwitcherProps {
+    /** Current theme. Supports `bind:theme`. @default 'system' */
+    theme?: Theme;
+    /**
+     * Interaction mode.
+     * - `'cycle'` — single button cycling light → dark → system (default)
+     * - `'toggle'` — single button toggling light ↔ dark (no system option)
+     * @default 'cycle'
+     */
+    strategy?: 'cycle' | 'toggle';
+    /** `localStorage` key for persistence. Set to `false` to disable. @default 'urbicon-theme' */
+    storageKey?: string | false;
+    /** Called after the theme changes. */
+    onThemeChange?: (theme: Theme) => void;
+    /** Visual style of the button. @default 'ghost' */
+    variant?: ThemeSwitcherVariants['variant'];
+    /** Button size. @default 'md' */
+    size?: ThemeSwitcherVariants['size'];
+    /** Additional CSS classes. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<'button' | 'icon', string>>;
+    /**
+     * Apply a named preset registered via `<BlocksProvider presets={{ ThemeSwitcher: {...} }}>`.
+     * Prefer this over `class` overrides when the requested look falls outside the
+     * semantic intent palette — presets keep hover/active/dark-mode logic coherent
+     * and make the custom look reusable across the project.
+     */
+    preset?: string;
+    /** Disable the switcher. */
+    disabled?: boolean;
+}
+export { default as ThemeSwitcher } from './ThemeSwitcher.svelte';
+export { type ThemeSwitcherVariants, themeSwitcherVariants } from './themeSwitcher.variants';

package/dist/components/ThemeSwitcher/index.js

@@ -0,0 +1,2 @@
+export { default as ThemeSwitcher } from './ThemeSwitcher.svelte';
+export { themeSwitcherVariants } from './themeSwitcher.variants';

package/dist/components/ThemeSwitcher/themeSwitcher.variants.d.ts

@@ -0,0 +1,51 @@
+import { type VariantProps } from '../../utils/variants';
+export declare const themeSwitcherVariants: (props?: import("../../utils/variants").TVProps<{
+    variant: {
+        ghost: {
+            button: string;
+        };
+        outlined: {
+            button: string;
+        };
+        filled: {
+            button: string;
+        };
+    };
+    size: {
+        sm: {
+            button: string;
+            icon: string;
+        };
+        md: {
+            button: string;
+            icon: string;
+        };
+        lg: {
+            button: string;
+            icon: string;
+        };
+    };
+    disabled: {
+        true: {
+            button: string;
+        };
+    };
+}> | undefined) => {
+    button: (props?: ({
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+        className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+    }) | undefined) => string;
+    icon: (props?: ({
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+        className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+    }) | undefined) => string;
+};
+export type ThemeSwitcherVariants = VariantProps<typeof themeSwitcherVariants>;

package/dist/components/ThemeSwitcher/themeSwitcher.variants.js

@@ -0,0 +1,35 @@
+import { tv } from '../../utils/variants';
+export const themeSwitcherVariants = tv({
+    slots: {
+        // tier: commit — icon-button action surface (mirrors Button default).
+        button: [
+            'inline-flex items-center justify-center rounded-commit',
+            'text-text-tertiary transition-colors',
+            'hover:bg-surface-hover hover:text-text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:ring-offset-2'
+        ],
+        icon: 'shrink-0'
+    },
+    variants: {
+        variant: {
+            ghost: { button: 'bg-transparent' },
+            outlined: {
+                button: 'border border-border-subtle bg-transparent hover:border-border-default'
+            },
+            filled: { button: 'bg-surface-subtle hover:bg-surface-hover' }
+        },
+        size: {
+            sm: { button: 'h-7 w-7', icon: 'h-3.5 w-3.5' },
+            md: { button: 'h-8 w-8', icon: 'h-4 w-4' },
+            lg: { button: 'h-10 w-10', icon: 'h-5 w-5' }
+        },
+        disabled: {
+            true: { button: 'pointer-events-none opacity-50' }
+        }
+    },
+    defaultVariants: {
+        variant: 'ghost',
+        size: 'md',
+        disabled: false
+    }
+});

package/dist/components/index.d.ts

@@ -0,0 +1,27 @@
+export type { CartesianDatum, ChartMargin, ChartPlot, ChartSeries, ChartSlotClasses } from '../internal/charts/types';
+export { arcPath, areaPath, type BandScale, bandScale, type ChartPoint, chartPalette, extent, linearScale, linePath, niceScale, numberFormatter, seriesColor } from '../internal/charts/utils';
+export { type ChartSlot, type ChartVariants, chartSlotResolver, chartVariants } from '../internal/charts/variants';
+export * from './AreaChart';
+export * from './BarChart';
+export type { CalendarContext, CalendarEvent, CalendarEventCategory, CalendarHeaderProps, CalendarProps, CalendarSelection, CalendarSlotName, CalendarViewMode, DateRange, DayCellContext, EventItemContext, HeaderContext } from './Calendar';
+export * from './Calendar';
+export * from './ChartFrame';
+export * from './CommandPalette';
+export type { CompositionBarIntent, CompositionBarProps, CompositionItem } from './CompositionBar';
+export * from './CompositionBar';
+export * from './CurrencyInput';
+export * from './DatePicker';
+export * from './DonutChart';
+export * from './EmptyState';
+export * from './FileUpload';
+export * from './Guide';
+export * from './LineChart';
+export type { LocaleSwitcherProps } from './LocaleSwitcher';
+export * from './LocaleSwitcher';
+export type { PlannerCellContext, PlannerDayContext, PlannerHeaderContext, PlannerProps, PlannerRange, PlannerSlotName, PlannerView } from './Planner';
+export * from './Planner';
+export type { SankeyIntent, SankeyLaidOutLinkWithMeta, SankeyLaidOutNodeWithMeta, SankeyLink, SankeyNode, SankeyProps } from './Sankey';
+export * from './Sankey';
+export * from './SidebarLayout';
+export * from './Sparkline';
+export * from './ThemeSwitcher';

package/dist/components/index.js

@@ -0,0 +1,22 @@
+// Shared chart utilities + types (the per-chart Props come via `export *` above).
+export { arcPath, areaPath, bandScale, chartPalette, extent, linearScale, linePath, niceScale, numberFormatter, seriesColor } from '../internal/charts/utils';
+export { chartSlotResolver, chartVariants } from '../internal/charts/variants';
+export * from './AreaChart';
+export * from './BarChart';
+export * from './Calendar';
+export * from './ChartFrame';
+export * from './CommandPalette';
+export * from './CompositionBar';
+export * from './CurrencyInput';
+export * from './DatePicker';
+export * from './DonutChart';
+export * from './EmptyState';
+export * from './FileUpload';
+export * from './Guide';
+export * from './LineChart';
+export * from './LocaleSwitcher';
+export * from './Planner';
+export * from './Sankey';
+export * from './SidebarLayout';
+export * from './Sparkline';
+export * from './ThemeSwitcher';

package/dist/date/compare.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Date comparison predicates and time-stripping helpers.
+ *
+ * All functions operate on **local** calendar days (no UTC conversion), so a
+ * `Date` constructed in the user's timezone compares the way they see it on a
+ * wall calendar. Part of the Svelte-free, server-capable `@urbicon-ui/blocks/date`
+ * layer.
+ */
+/** Strip the time component, returning local midnight of the same calendar day. */
+export declare function stripTime(date: Date): Date;
+/** Check whether two dates fall on the same calendar day (ignoring time). */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/**
+ * Check whether a date is a weekend day (Saturday or Sunday).
+ *
+ * Weekend is defined as Saturday + Sunday regardless of `weekStartsOn` — the
+ * day a week is laid out from does not change which days are non-working. A
+ * locale-specific weekend (e.g. Friday + Saturday) is intentionally out of
+ * scope; add an explicit option if a consumer ever needs it.
+ */
+export declare function isWeekend(date: Date): boolean;
+/** Check whether a date falls within a range (inclusive on both ends, order-independent). */
+export declare function isInRange(date: Date, start: Date, end: Date): boolean;
+/** Check whether a date belongs to the given month and year. */
+export declare function isInMonth(date: Date, month: number, year: number): boolean;
+/**
+ * DST-safe count of whole calendar days from `a` to `b`.
+ * Positive when `b` is after `a`. Computed via UTC midnight to avoid
+ * daylight-saving hour shifts skewing the division.
+ */
+export declare function daysBetween(a: Date, b: Date): number;

package/dist/date/compare.js

@@ -0,0 +1,51 @@
+/**
+ * Date comparison predicates and time-stripping helpers.
+ *
+ * All functions operate on **local** calendar days (no UTC conversion), so a
+ * `Date` constructed in the user's timezone compares the way they see it on a
+ * wall calendar. Part of the Svelte-free, server-capable `@urbicon-ui/blocks/date`
+ * layer.
+ */
+/** Strip the time component, returning local midnight of the same calendar day. */
+export function stripTime(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+/** Check whether two dates fall on the same calendar day (ignoring time). */
+export function isSameDay(a, b) {
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate());
+}
+/**
+ * Check whether a date is a weekend day (Saturday or Sunday).
+ *
+ * Weekend is defined as Saturday + Sunday regardless of `weekStartsOn` — the
+ * day a week is laid out from does not change which days are non-working. A
+ * locale-specific weekend (e.g. Friday + Saturday) is intentionally out of
+ * scope; add an explicit option if a consumer ever needs it.
+ */
+export function isWeekend(date) {
+    const day = date.getDay();
+    return day === 0 || day === 6;
+}
+/** Check whether a date falls within a range (inclusive on both ends, order-independent). */
+export function isInRange(date, start, end) {
+    const d = stripTime(date).getTime();
+    const s = stripTime(start).getTime();
+    const e = stripTime(end).getTime();
+    return d >= Math.min(s, e) && d <= Math.max(s, e);
+}
+/** Check whether a date belongs to the given month and year. */
+export function isInMonth(date, month, year) {
+    return date.getMonth() === month && date.getFullYear() === year;
+}
+/**
+ * DST-safe count of whole calendar days from `a` to `b`.
+ * Positive when `b` is after `a`. Computed via UTC midnight to avoid
+ * daylight-saving hour shifts skewing the division.
+ */
+export function daysBetween(a, b) {
+    const utcA = Date.UTC(a.getFullYear(), a.getMonth(), a.getDate());
+    const utcB = Date.UTC(b.getFullYear(), b.getMonth(), b.getDate());
+    return Math.round((utcB - utcA) / 86400000);
+}

package/dist/date/format.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Locale-aware date formatting built on the native `Intl.DateTimeFormat`.
+ * No locale tables are bundled — output follows the runtime's ICU data for the
+ * given BCP 47 locale tag.
+ */
+/**
+ * Get localized weekday names.
+ *
+ * @param locale - BCP 47 locale tag (e.g. 'de-DE')
+ * @param weekStartsOn - Day the week starts on (0=Sun, 1=Mon)
+ * @param format - Name format ('narrow'='M', 'short'='Mo', 'long'='Montag')
+ * @returns Array of 7 weekday name strings, ordered from `weekStartsOn`
+ */
+export declare function getWeekdayNames(locale?: string, weekStartsOn?: number, format?: 'narrow' | 'short' | 'long'): string[];
+/** Format month and year for header display, e.g. "März 2026", "March 2026". */
+export declare function formatMonthYear(year: number, month: number, locale?: string): string;
+/** Format a date for a detail header, e.g. "Do, 12. März", "Thu, March 12". */
+export declare function formatDate(date: Date, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/** Format a date for a screen-reader label, e.g. "Donnerstag, 12. März 2026". */
+export declare function formatDateFull(date: Date, locale?: string): string;
+/**
+ * Format a week title for a header, e.g. "KW 12 – März 2026" (de-DE) or
+ * "Week 12 – March 2026" (en-US). Uses the week's Thursday to pick the
+ * month/year (ISO week convention).
+ */
+export declare function formatWeekTitle(date: Date, weekStartsOn?: number, locale?: string): string;
+/**
+ * Format the date span of the week containing `date`, e.g. "15.–21. Juni"
+ * (de-DE) or "Jun 15 – 21" (en-US). The exact shape — and whether the shared
+ * month collapses — follows the locale via `Intl.DateTimeFormat.formatRange`.
+ */
+export declare function formatWeekRange(date: Date, locale?: string, weekStartsOn?: number): string;
+/**
+ * Format an arbitrary date span including the year, e.g. "15. Juni – 5. Juli
+ * 2026" (de-DE). Collapses shared month/year parts per the locale via
+ * `Intl.DateTimeFormat.formatRange`. Suited to a multi-week range-view title;
+ * for a single ISO week prefer {@link formatWeekRange}.
+ */
+export declare function formatDateRange(start: Date, end: Date, locale?: string): string;
+/**
+ * Format a day-view header, e.g. "Do, 19. März 2026" (de-DE) or
+ * "Thu, March 19, 2026" (en-US).
+ */
+export declare function formatDayTitle(date: Date, locale?: string): string;
+/**
+ * Format an abbreviated month name for the year grid, e.g. "Mär" (de-DE) or
+ * "Mar" (en-US).
+ *
+ * @param month - Month index (0-11)
+ * @param locale - BCP 47 locale tag
+ */
+export declare function formatMonthShort(month: number, locale?: string): string;

package/dist/date/format.js

@@ -0,0 +1,129 @@
+/**
+ * Locale-aware date formatting built on the native `Intl.DateTimeFormat`.
+ * No locale tables are bundled — output follows the runtime's ICU data for the
+ * given BCP 47 locale tag.
+ */
+import { getWeekDates, getWeekNumber } from './geometry';
+/** Localized week-number labels for the `formatWeekTitle` prefix (e.g. "KW"). */
+const WEEK_LABELS = {
+    de: 'KW',
+    en: 'Week',
+    fr: 'Sem.',
+    es: 'Sem.',
+    it: 'Sett.',
+    nl: 'Week',
+    pt: 'Sem.'
+};
+/**
+ * Get localized weekday names.
+ *
+ * @param locale - BCP 47 locale tag (e.g. 'de-DE')
+ * @param weekStartsOn - Day the week starts on (0=Sun, 1=Mon)
+ * @param format - Name format ('narrow'='M', 'short'='Mo', 'long'='Montag')
+ * @returns Array of 7 weekday name strings, ordered from `weekStartsOn`
+ */
+export function getWeekdayNames(locale = 'de-DE', weekStartsOn = 1, format = 'short') {
+    const formatter = new Intl.DateTimeFormat(locale, { weekday: format });
+    const names = [];
+    // Anchor on a known week (2026-01-04 is a Sunday, 2026-01-05 a Monday).
+    const baseMonday = new Date(2026, 0, 5);
+    const baseSunday = new Date(2026, 0, 4);
+    const baseDate = weekStartsOn === 0 ? baseSunday : new Date(baseMonday);
+    if (weekStartsOn > 1) {
+        baseDate.setDate(baseDate.getDate() + (weekStartsOn - 1));
+    }
+    for (let i = 0; i < 7; i++) {
+        const date = new Date(baseDate);
+        date.setDate(date.getDate() + i);
+        names.push(formatter.format(date));
+    }
+    return names;
+}
+/** Format month and year for header display, e.g. "März 2026", "March 2026". */
+export function formatMonthYear(year, month, locale = 'de-DE') {
+    const date = new Date(year, month, 1);
+    return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(date);
+}
+/** Format a date for a detail header, e.g. "Do, 12. März", "Thu, March 12". */
+export function formatDate(date, locale = 'de-DE', options) {
+    const defaultOptions = {
+        weekday: 'short',
+        day: 'numeric',
+        month: 'long'
+    };
+    return new Intl.DateTimeFormat(locale, options ?? defaultOptions).format(date);
+}
+/** Format a date for a screen-reader label, e.g. "Donnerstag, 12. März 2026". */
+export function formatDateFull(date, locale = 'de-DE') {
+    return new Intl.DateTimeFormat(locale, {
+        weekday: 'long',
+        day: 'numeric',
+        month: 'long',
+        year: 'numeric'
+    }).format(date);
+}
+/**
+ * Format a week title for a header, e.g. "KW 12 – März 2026" (de-DE) or
+ * "Week 12 – March 2026" (en-US). Uses the week's Thursday to pick the
+ * month/year (ISO week convention).
+ */
+export function formatWeekTitle(date, weekStartsOn = 1, locale = 'de-DE') {
+    const weekDates = getWeekDates(date, weekStartsOn);
+    // ISO convention: Thursday decides the month/year the week belongs to.
+    const thursday = weekDates[(4 - weekStartsOn + 7) % 7];
+    const weekNum = getWeekNumber(thursday);
+    const monthYear = new Intl.DateTimeFormat(locale, {
+        month: 'long',
+        year: 'numeric'
+    }).format(thursday);
+    const lang = locale.split('-')[0];
+    const weekLabel = WEEK_LABELS[lang] ?? 'Week';
+    return `${weekLabel} ${weekNum} – ${monthYear}`;
+}
+/**
+ * Format the date span of the week containing `date`, e.g. "15.–21. Juni"
+ * (de-DE) or "Jun 15 – 21" (en-US). The exact shape — and whether the shared
+ * month collapses — follows the locale via `Intl.DateTimeFormat.formatRange`.
+ */
+export function formatWeekRange(date, locale = 'de-DE', weekStartsOn = 1) {
+    const weekDates = getWeekDates(date, weekStartsOn);
+    const formatter = new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'long' });
+    return formatter.formatRange(weekDates[0], weekDates[6]);
+}
+/**
+ * Format an arbitrary date span including the year, e.g. "15. Juni – 5. Juli
+ * 2026" (de-DE). Collapses shared month/year parts per the locale via
+ * `Intl.DateTimeFormat.formatRange`. Suited to a multi-week range-view title;
+ * for a single ISO week prefer {@link formatWeekRange}.
+ */
+export function formatDateRange(start, end, locale = 'de-DE') {
+    const formatter = new Intl.DateTimeFormat(locale, {
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric'
+    });
+    return formatter.formatRange(start, end);
+}
+/**
+ * Format a day-view header, e.g. "Do, 19. März 2026" (de-DE) or
+ * "Thu, March 19, 2026" (en-US).
+ */
+export function formatDayTitle(date, locale = 'de-DE') {
+    return new Intl.DateTimeFormat(locale, {
+        weekday: 'short',
+        day: 'numeric',
+        month: 'long',
+        year: 'numeric'
+    }).format(date);
+}
+/**
+ * Format an abbreviated month name for the year grid, e.g. "Mär" (de-DE) or
+ * "Mar" (en-US).
+ *
+ * @param month - Month index (0-11)
+ * @param locale - BCP 47 locale tag
+ */
+export function formatMonthShort(month, locale = 'de-DE') {
+    const date = new Date(2026, month, 1);
+    return new Intl.DateTimeFormat(locale, { month: 'short' }).format(date);
+}