@urbicon-ui/blocks 6.1.4

package/dist/components/Planner/Planner.svelte

@@ -0,0 +1,346 @@
+<script lang="ts" generics="T = unknown">
+  import { useBlocksI18n } from '../..';
+  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { stripTime } from '../../date';
+  import {
+    DateGridController,
+    DateGridScaffold,
+    setDateGridContext,
+    type DateGridRange,
+    type DateGridSelection,
+    type DateGridView,
+    type DayCellInfo,
+    type DayHeaderInfo
+  } from '../../internal/date-grid';
+  import { bucketItemsByDate } from './planner.bucket';
+  import { setPlannerContext } from './planner.context';
+  import { plannerVariants } from './planner.variants';
+  import type {
+    PlannerCellContext,
+    PlannerContext,
+    PlannerDayContext,
+    PlannerHeaderContext,
+    PlannerSlotName
+  } from './planner.types';
+  import PlannerHeader from './PlannerHeader.svelte';
+  import type { PlannerProps } from './index';
+
+  let {
+    // Content / data
+    items = [],
+    getDate,
+    sort,
+    // View
+    view = 'week',
+    rangeStart = $bindable(undefined),
+    rangeEnd = $bindable(undefined),
+    weekStartsOn = 1,
+    locale = 'de-DE',
+    showWeekNumber = false,
+    // State
+    value = $bindable(undefined),
+    selectedDate = $bindable(undefined),
+    // Variants
+    variant = 'default',
+    size = 'md',
+    // Behavior
+    highlightToday = true,
+    highlightWeekend = false,
+    swipeable: swipeableProp = true,
+    animated = true,
+    disabled = false,
+    // Callbacks
+    onNavigate,
+    onDateSelect,
+    // Snippets
+    header,
+    dayHeader,
+    cell,
+    empty,
+    // Styling
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: PlannerProps<T> = $props();
+
+  const bt = useBlocksI18n();
+
+  // --- BlocksConfig integration ---
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const slotClasses = $derived(
+    mergeSlotClasses(
+      blocksConfig?.defaults?.Planner?.slotClasses,
+      resolvePresetSlotClasses(blocksConfig?.presets, 'Planner', preset),
+      slotClassesProp
+    )
+  );
+
+  // --- Styling: one tv() instance, resolved per slot ---
+  const styles = $derived(plannerVariants({ view, variant, size }));
+  function slot(name: PlannerSlotName, extra?: string): string {
+    const overrides = [slotClasses?.[name], extra].filter(Boolean).join(' ');
+    if (unstyled) return overrides;
+    const fn = styles[name] as ((args: { class: string }) => string) | undefined;
+    return fn?.({ class: overrides }) ?? overrides;
+  }
+
+  // --- Reference date: controlled by `value`, else internal state seeded once ---
+  let internalRef = $state(stripTime(value ?? selectedDate ?? new Date()));
+  const referenceDate = $derived(value !== undefined ? stripTime(value) : internalRef);
+  function setReference(next: Date) {
+    const d = stripTime(next);
+    internalRef = d;
+    if (value !== undefined) value = d;
+  }
+
+  // --- Headless mechanics: Planner owns the source of truth, the controller
+  // computes geometry/queries and reports navigation/selection back. Single
+  // selection only (D5); range/multiple stay Calendar's. ---
+  const controller = new DateGridController({
+    get referenceDate() {
+      return referenceDate;
+    },
+    get view() {
+      return view as DateGridView;
+    },
+    get weekStartsOn() {
+      return weekStartsOn;
+    },
+    get locale() {
+      return locale;
+    },
+    get selectionMode() {
+      return 'single' as const;
+    },
+    get selection() {
+      return selectedDate as DateGridSelection | undefined;
+    },
+    get rangeStart() {
+      return rangeStart;
+    },
+    get rangeEnd() {
+      return rangeEnd;
+    },
+    get minDate() {
+      return undefined;
+    },
+    get maxDate() {
+      return undefined;
+    },
+    get disabled() {
+      return disabled;
+    },
+    onNavigate: handleNavigate,
+    onSelect: handleSelect
+  });
+
+  function handleNavigate(next: Date, range: DateGridRange) {
+    setReference(next);
+    if (view === 'range') {
+      // The range window follows rangeStart/rangeEnd, so navigation rebinds them
+      // from the shifted window the controller computed.
+      rangeStart = range.start;
+      rangeEnd = range.end;
+    }
+    onNavigate?.(next, { start: range.start, end: range.end });
+  }
+
+  function handleSelect(_selection: DateGridSelection, date: Date) {
+    selectedDate = date; // single mode — the selection is the clicked date
+    onDateSelect?.(date);
+  }
+
+  // Midnight refresh for `today` — re-arms after each update via the reactive read.
+  $effect(() => {
+    const _today = controller.today;
+    if (typeof window === 'undefined') return;
+    const now = new Date(); // eslint-disable-line svelte/prefer-svelte-reactivity
+    const midnight = new Date(now); // eslint-disable-line svelte/prefer-svelte-reactivity
+    midnight.setHours(24, 0, 0, 0);
+    const timeout = setTimeout(() => controller.refreshToday(), midnight.getTime() - now.getTime());
+    return () => clearTimeout(timeout);
+  });
+
+  // --- Bucket items by local day; the cell snippet receives the typed slice ---
+  const buckets = $derived(bucketItemsByDate(items, getDate, sort));
+
+  function plannerCellContext(info: DayCellInfo): PlannerCellContext<T> {
+    return {
+      date: info.date,
+      isoDate: info.isoDate,
+      items: buckets.get(info.isoDate) ?? [],
+      isToday: info.isToday,
+      isSelected: controller.isSelected(info.date),
+      isWeekend: info.isWeekend,
+      isOutsideRange: info.isOutside,
+      weekNumber: info.weekNumber,
+      weekday: weekdayName(info.date),
+      selectDate: () => controller.selectDate(info.date)
+    };
+  }
+
+  function plannerDayContext(info: DayHeaderInfo): PlannerDayContext {
+    const date = info.date;
+    return {
+      date,
+      isoDate: date ? controller.dayCellInfo(date).isoDate : undefined,
+      weekday: info.weekday,
+      isToday: date ? controller.isToday(date) : false,
+      isWeekend: info.isWeekend,
+      weekNumber: date ? controller.weekNumberFor(date) : undefined
+    };
+  }
+
+  // Short weekday name for a date (for stacked week cells), via the locale.
+  const weekdayFormatter = $derived(new Intl.DateTimeFormat(locale, { weekday: 'short' }));
+  function weekdayName(date: Date): string {
+    return weekdayFormatter.format(date);
+  }
+
+  // --- Per-cell state classes (dynamic; not part of the static variant matrix) ---
+  const todayDateMark = 'bg-primary text-text-on-primary rounded-full';
+  function cellStateClasses(p: PlannerCellContext<T>): Array<string | false> {
+    return [
+      p.isSelected && 'ring-2 ring-primary ring-inset relative z-10',
+      highlightWeekend && p.isWeekend && 'bg-surface-subtle',
+      p.isOutsideRange && 'opacity-40'
+    ];
+  }
+
+  const isWeek = $derived(view === 'week');
+
+  // --- Header context (for the `header` snippet) ---
+  const headerContext = $derived<PlannerHeaderContext>({
+    title: controller.title,
+    rangeStart: controller.rangeStart,
+    rangeEnd: controller.rangeEnd,
+    weekNumber: controller.weekNumberFor(referenceDate),
+    view,
+    navigate: (delta) => controller.navigate(delta),
+    goToToday: () => controller.goToToday(),
+    goTo: (date) => controller.goTo(date),
+    canGoBack: controller.canGoBack,
+    canGoForward: controller.canGoForward
+  });
+
+  // --- Contexts: the controller IS the date-grid context the Scaffold reads;
+  // PlannerHeader reads the lighter Planner context. ---
+  setDateGridContext(controller);
+
+  const plannerCtx: PlannerContext = {
+    get view() {
+      return view;
+    },
+    get title() {
+      return controller.title;
+    },
+    get rangeStart() {
+      return controller.rangeStart;
+    },
+    get rangeEnd() {
+      return controller.rangeEnd;
+    },
+    get weekNumber() {
+      return controller.weekNumberFor(referenceDate);
+    },
+    get canGoBack() {
+      return controller.canGoBack;
+    },
+    get canGoForward() {
+      return controller.canGoForward;
+    },
+    get locale() {
+      return locale;
+    },
+    get disabled() {
+      return disabled;
+    },
+    navigate: (delta) => controller.navigate(delta),
+    goToToday: () => controller.goToToday(),
+    goTo: (date) => controller.goTo(date),
+    slot
+  };
+  setPlannerContext(plannerCtx);
+</script>
+
+<div class={slot('base', className)} {...restProps}>
+  <div class="sr-only" aria-live="polite" role="status">{controller.title}</div>
+
+  {#if header}
+    {@render header(headerContext)}
+  {:else}
+    <PlannerHeader />
+  {/if}
+
+  <DateGridScaffold
+    class={slot('grid', !isWeek ? 'border-r border-b border-border-subtle' : '')}
+    {showWeekNumber}
+    swipeable={swipeableProp && !disabled}
+    {animated}
+    ariaLabel={bt('planner.grid')}
+    headerRowClass={slot('weekdayHeader', isWeek ? 'gap-2 max-md:hidden' : '')}
+    headerClass={slot('weekday')}
+    rowClass={slot('week', isWeek ? 'gap-2 max-md:grid-cols-1' : '')}
+    cellClass="h-auto"
+    weekNumberClass={slot('weekNumber')}
+    cell={gridCell}
+    dayHeader={gridDayHeader}
+  />
+</div>
+
+{#snippet gridDayHeader(info: DayHeaderInfo)}
+  {#if dayHeader}
+    {@render dayHeader(plannerDayContext(info))}
+  {:else}
+    <span class="inline-flex items-center justify-center gap-1">
+      {info.weekday}
+      {#if isWeek && info.date}
+        {@const isToday = controller.isToday(info.date)}
+        <span class={['tabular-nums', isToday && 'text-primary font-bold']}>
+          {info.date.getDate()}
+        </span>
+      {/if}
+    </span>
+  {/if}
+{/snippet}
+
+{#snippet gridCell(info: DayCellInfo)}
+  {@const p = plannerCellContext(info)}
+  <div class={[slot('cell'), ...cellStateClasses(p)]}>
+    <!-- Date header: week shows weekday+date only when stacked (mobile); month/range always. -->
+    <div class={[slot('cellHeader'), isWeek && 'md:hidden']}>
+      {#if isWeek}
+        <span class={slot('cellWeekday')}>{p.weekday}</span>
+      {/if}
+      <span
+        class={[
+          slot('cellDate'),
+          highlightToday && p.isToday ? todayDateMark : 'text-text-secondary'
+        ]}
+      >
+        {info.date.getDate()}
+      </span>
+    </div>
+
+    {#if p.items.length === 0 && empty}
+      <!-- Empty day, and the consumer supplied a dedicated placeholder, which
+           takes precedence over `cell` for empty days. -->
+      <div class={slot('empty')}>{@render empty(p)}</div>
+    {:else if cell}
+      <!-- `cell` drives content. With no `empty` snippet it is called for empty
+           days too (`items` is `[]`), so an "add" affordance can live here. -->
+      <div class={slot('cellItems')}>{@render cell(p)}</div>
+    {:else if p.items.length > 0}
+      <!-- No cell snippet: a language-neutral count so bucketing is visible. -->
+      <span
+        class="bg-primary-subtle text-primary inline-flex h-5 min-w-5 items-center justify-center rounded-full px-1 text-xs font-medium tabular-nums"
+        aria-label={bt('planner.itemCount', { count: p.items.length })}
+      >
+        {p.items.length}
+      </span>
+    {/if}
+  </div>
+{/snippet}

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

@@ -0,0 +1,25 @@
+import type { PlannerProps } from './index';
+declare function $$render<T = unknown>(): {
+    props: PlannerProps<T>;
+    exports: {};
+    bindings: "value" | "rangeStart" | "rangeEnd" | "selectedDate";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T = unknown> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "value" | "rangeStart" | "rangeEnd" | "selectedDate";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Planner: $$IsomorphicComponent;
+type Planner<T = unknown> = InstanceType<typeof Planner<T>>;
+export default Planner;

package/dist/components/Planner/PlannerHeader.svelte

@@ -0,0 +1,80 @@
+<!--
+  PlannerHeader — the default Planner toolbar.
+
+  prev / title / today / next, reading mechanics from the Planner context. The
+  whole bar is replaceable via Planner's `header` snippet; this is the fallback.
+-->
+<script lang="ts">
+  import { useBlocksI18n } from '../..';
+  import { Button } from '../../primitives/Button';
+  import { Tooltip } from '../../primitives/Tooltip';
+  import { resolveIcon } from '../../icons';
+  import ChevronLeftIconDefault from '../../icons/ChevronLeftIcon.svelte';
+  import ChevronRightIconDefault from '../../icons/ChevronRightIcon.svelte';
+  import CalendarDaysIconDefault from '../../icons/CalendarDaysIcon.svelte';
+  import { getPlannerContext } from './planner.context';
+
+  const bt = useBlocksI18n();
+  const ctx = getPlannerContext();
+
+  const ChevronLeftIcon = resolveIcon('chevronLeft', ChevronLeftIconDefault);
+  const ChevronRightIcon = resolveIcon('chevronRight', ChevronRightIconDefault);
+  const CalendarDaysIcon = resolveIcon('calendarDays', CalendarDaysIconDefault);
+
+  const prevLabel = $derived(
+    ctx.view === 'month'
+      ? bt('planner.previousMonth')
+      : ctx.view === 'range'
+        ? bt('planner.previousRange')
+        : bt('planner.previousWeek')
+  );
+  const nextLabel = $derived(
+    ctx.view === 'month'
+      ? bt('planner.nextMonth')
+      : ctx.view === 'range'
+        ? bt('planner.nextRange')
+        : bt('planner.nextWeek')
+  );
+</script>
+
+<div class={ctx.slot('header')}>
+  <div class={ctx.slot('nav')}>
+    <Button
+      unstyled
+      mint="none"
+      class={ctx.slot('navButton')}
+      onclick={() => ctx.navigate(-1)}
+      disabled={!ctx.canGoBack || ctx.disabled}
+      aria-label={prevLabel}
+    >
+      <ChevronLeftIcon size={16} />
+    </Button>
+  </div>
+
+  <span class={ctx.slot('headerTitle')}>{ctx.title}</span>
+
+  <div class={ctx.slot('nav')}>
+    <Tooltip label={bt('planner.today')}>
+      <Button
+        unstyled
+        mint="none"
+        class={ctx.slot('navButton')}
+        onclick={() => ctx.goToToday()}
+        disabled={ctx.disabled}
+        aria-label={bt('planner.today')}
+      >
+        <CalendarDaysIcon size={16} />
+      </Button>
+    </Tooltip>
+    <Button
+      unstyled
+      mint="none"
+      class={ctx.slot('navButton')}
+      onclick={() => ctx.navigate(1)}
+      disabled={!ctx.canGoForward || ctx.disabled}
+      aria-label={nextLabel}
+    >
+      <ChevronRightIcon size={16} />
+    </Button>
+  </div>
+</div>

package/dist/components/Planner/PlannerHeader.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const PlannerHeader: import("svelte").Component<Record<string, never>, {}, "">;
+type PlannerHeader = ReturnType<typeof PlannerHeader>;
+export default PlannerHeader;

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

@@ -0,0 +1,110 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { PlannerCellContext, PlannerDayContext, PlannerHeaderContext, PlannerRange, PlannerSlotName, PlannerView } from './planner.types';
+import type { PlannerVariants } from './planner.variants';
+/**
+ * @description Date-indexed planning board — a week, month or custom-range grid
+ * whose cells hold YOUR domain content (meals, shifts, bookings, content slots)
+ * via a generic `cell` snippet. Buckets `items` by calendar day, then handles
+ * navigation, ISO week numbers, keyboard a11y and a responsive column→stack
+ * layout. For timed appointments, multi-day spans or recurrence use `Calendar`
+ * instead.
+ *
+ * @tag display
+ * @tag layout
+ * @related Calendar
+ * @related DatePicker
+ * @stability beta
+ *
+ * @example Weekly meal plan — `items` are bucketed by `getDate`, rendered by `cell`
+ * ```svelte
+ * <Planner view="week" items={entries} getDate={(e) => e.date}
+ *          sort={(a, b) => MEAL_ORDER[a.mealType] - MEAL_ORDER[b.mealType]}
+ *          bind:value={referenceDate} onNavigate={(_, range) => loadWeek(range.start)}>
+ *   {#snippet cell({ items, isoDate })}
+ *     {#each items as entry (entry.id)}
+ *       <MealCard {entry} />
+ *     {/each}
+ *     <Button variant="ghost" size="sm" onclick={() => openAdd(isoDate)}>Add meal</Button>
+ *   {/snippet}
+ * </Planner>
+ * ```
+ */
+export interface PlannerProps<T = unknown> extends Omit<PlannerVariants, 'view'>, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** The items to lay out. Each is bucketed onto a day via {@link getDate}. */
+    items?: T[];
+    /**
+     * Map an item to its calendar day. Return a `Date`, or a local date string
+     * (`'2026-06-16'`) taken verbatim — never UTC-parsed, so a plain date never
+     * shifts across timezones. A date-*time* string is bucketed by its written
+     * date part too; if your value is a UTC instant whose local day matters
+     * (`'…T23:00:00Z'`), return `new Date(value)` so the local timezone applies.
+     * Required.
+     */
+    getDate: (item: T) => Date | string;
+    /** Comparator for items within a day cell (e.g. by meal type or start label). */
+    sort?: (a: T, b: T) => number;
+    /** Layout mode. @default 'week' */
+    view?: PlannerView;
+    /** Start of the window for `view="range"`. */
+    rangeStart?: Date;
+    /** End of the window for `view="range"`. */
+    rangeEnd?: Date;
+    /** First day of the week (0=Sun … 6=Sat). @default 1 */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** BCP 47 locale for the title and weekday names. @default 'de-DE' */
+    locale?: string;
+    /** Show the ISO week-number column on the left. @default false */
+    showWeekNumber?: boolean;
+    /** Reference date the view is anchored on. Supports `bind:value`. @default today */
+    value?: Date;
+    /** The active highlighted day. Supports `bind:selectedDate`. */
+    selectedDate?: Date;
+    /** Visual treatment. @default 'default' */
+    variant?: 'default' | 'bordered' | 'ghost';
+    /** Density of the grid and header. @default 'md' */
+    size?: 'sm' | 'md' | 'lg';
+    /** Visually mark today's cell. @default true */
+    highlightToday?: boolean;
+    /** Tint Saturday/Sunday cells. @default false */
+    highlightWeekend?: boolean;
+    /** Enable horizontal swipe-to-navigate on touch. @default true */
+    swipeable?: boolean;
+    /** Slide-transition the grid on navigate (respects reduced-motion). @default true */
+    animated?: boolean;
+    /** Disable navigation and selection. @default false */
+    disabled?: boolean;
+    /** Fires after navigation. Receives the new reference date and visible range — load data here. */
+    onNavigate?: (date: Date, range: PlannerRange) => void;
+    /** Fires when a day cell is activated (click / Enter / Space). */
+    onDateSelect?: (date: Date) => void;
+    /** Replace the default toolbar (prev/next/today/title/week). */
+    header?: Snippet<[PlannerHeaderContext]>;
+    /** Customise each weekday/column header. */
+    dayHeader?: Snippet<[PlannerDayContext]>;
+    /**
+     * Render a day's content — the core of the API. Receives bucketed `items: T[]`.
+     * Called for **every** day, including empty ones (`items: []`) — unless an
+     * `empty` snippet is given, which then handles empty days instead. Put an
+     * "add" affordance here to keep it available on empty days.
+     */
+    cell?: Snippet<[PlannerCellContext<T>]>;
+    /**
+     * Placeholder rendered **instead of** `cell` for days with no items. Omit it
+     * to let `cell` render empty days too.
+     */
+    empty?: Snippet<[PlannerCellContext<T>]>;
+    /** Extra classes merged onto the root element. */
+    class?: string;
+    /** Remove all default tv() classes — only user-provided classes apply. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides merged with tv() styles. */
+    slotClasses?: Partial<Record<PlannerSlotName, string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ Planner: {...} }}>`. */
+    preset?: string;
+}
+export { default as Planner } from './Planner.svelte';
+export { default as PlannerHeader } from './PlannerHeader.svelte';
+export { bucketItemsByDate, type GetItemDate, toDateKey } from './planner.bucket';
+export type { PlannerCellContext, PlannerDayContext, PlannerHeaderContext, PlannerRange, PlannerSlotName, PlannerView } from './planner.types';
+export { type PlannerVariants, plannerVariants } from './planner.variants';

package/dist/components/Planner/index.js

@@ -0,0 +1,4 @@
+export { default as Planner } from './Planner.svelte';
+export { default as PlannerHeader } from './PlannerHeader.svelte';
+export { bucketItemsByDate, toDateKey } from './planner.bucket';
+export { plannerVariants } from './planner.variants';

package/dist/components/Planner/planner.bucket.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure item-bucketing for the Planner — the headless core of layer 2b.
+ *
+ * Groups a flat `T[]` into per-day buckets keyed by local ISO date
+ * (`YYYY-MM-DD`), the single value Planner's `cell` snippet receives. Kept
+ * Svelte-free and side-effect-free so it unit-tests without a DOM and stays the
+ * one place the date→key normalisation lives.
+ */
+/** Maps an item to its calendar day — a `Date` or a local ISO date string. */
+export type GetItemDate<T> = (item: T) => Date | string;
+/**
+ * Derive the local `YYYY-MM-DD` bucket key for an item's date.
+ *
+ * A date-first string (`'2026-06-16'`, optionally with a time suffix) is sliced
+ * to its **written** date part without parsing — `new Date('2026-06-16')` would
+ * read it as UTC midnight and shift a day west of Greenwich. This preserves the
+ * "everything local, never UTC" contract Planner inherits from
+ * `@urbicon-ui/blocks/date`. The trade-off: a UTC *instant* string
+ * (`'2026-06-16T23:00:00Z'`) buckets on its written day (16 Jun), not the local
+ * day it may fall on — callers who need instant→local conversion pass a `Date`.
+ * A `Date` is always reduced to its local calendar day.
+ */
+export declare function toDateKey(raw: Date | string): string;
+/**
+ * Bucket `items` by their local calendar day.
+ *
+ * Returns a `Map` from local ISO date (`YYYY-MM-DD`) to the items on that day,
+ * in input order. When `sort` is supplied each bucket is sorted in place,
+ * giving the `cell` snippet a stable intra-day order (e.g. meal-type ordering).
+ * Days with no items are simply absent from the map.
+ */
+export declare function bucketItemsByDate<T>(items: readonly T[], getDate: GetItemDate<T>, sort?: (a: T, b: T) => number): Map<string, T[]>;

package/dist/components/Planner/planner.bucket.js

@@ -0,0 +1,54 @@
+/**
+ * Pure item-bucketing for the Planner — the headless core of layer 2b.
+ *
+ * Groups a flat `T[]` into per-day buckets keyed by local ISO date
+ * (`YYYY-MM-DD`), the single value Planner's `cell` snippet receives. Kept
+ * Svelte-free and side-effect-free so it unit-tests without a DOM and stays the
+ * one place the date→key normalisation lives.
+ */
+import { toIso } from '../../date';
+/**
+ * Derive the local `YYYY-MM-DD` bucket key for an item's date.
+ *
+ * A date-first string (`'2026-06-16'`, optionally with a time suffix) is sliced
+ * to its **written** date part without parsing — `new Date('2026-06-16')` would
+ * read it as UTC midnight and shift a day west of Greenwich. This preserves the
+ * "everything local, never UTC" contract Planner inherits from
+ * `@urbicon-ui/blocks/date`. The trade-off: a UTC *instant* string
+ * (`'2026-06-16T23:00:00Z'`) buckets on its written day (16 Jun), not the local
+ * day it may fall on — callers who need instant→local conversion pass a `Date`.
+ * A `Date` is always reduced to its local calendar day.
+ */
+export function toDateKey(raw) {
+    if (typeof raw === 'string') {
+        // Fast path: a date-first string → take the written day part verbatim.
+        if (/^\d{4}-\d{2}-\d{2}/.test(raw))
+            return raw.slice(0, 10);
+        return toIso(new Date(raw));
+    }
+    return toIso(raw);
+}
+/**
+ * Bucket `items` by their local calendar day.
+ *
+ * Returns a `Map` from local ISO date (`YYYY-MM-DD`) to the items on that day,
+ * in input order. When `sort` is supplied each bucket is sorted in place,
+ * giving the `cell` snippet a stable intra-day order (e.g. meal-type ordering).
+ * Days with no items are simply absent from the map.
+ */
+export function bucketItemsByDate(items, getDate, sort) {
+    const buckets = new Map();
+    for (const item of items) {
+        const key = toDateKey(getDate(item));
+        const bucket = buckets.get(key);
+        if (bucket)
+            bucket.push(item);
+        else
+            buckets.set(key, [item]);
+    }
+    if (sort) {
+        for (const bucket of buckets.values())
+            bucket.sort(sort);
+    }
+    return buckets;
+}

package/dist/components/Planner/planner.context.d.ts

@@ -0,0 +1,5 @@
+import type { PlannerContext } from './planner.types';
+declare const setPlannerContext: (value: PlannerContext | undefined) => PlannerContext | undefined;
+export { setPlannerContext };
+/** Read the Planner context. Throws if used outside a `<Planner>`. */
+export declare function getPlannerContext(): PlannerContext;

package/dist/components/Planner/planner.context.js

@@ -0,0 +1,13 @@
+import { createOptionalContext } from '../../utils/optional-context';
+// Optional context so the getter can throw a descriptive error rather than
+// Svelte's generic missing_context.
+const [getPlannerContextRaw, setPlannerContext] = createOptionalContext();
+export { setPlannerContext };
+/** Read the Planner context. Throws if used outside a `<Planner>`. */
+export function getPlannerContext() {
+    const ctx = getPlannerContextRaw();
+    if (!ctx) {
+        throw new Error('PlannerHeader and its siblings must be used inside a <Planner>.');
+    }
+    return ctx;
+}