# Week Strip
Days in a row that move a week at a time.
Source page: https://dinachi.dev/docs/components/week-strip

## Installation
```bash
npx @dinachi/cli@latest add week-strip
```
Adds to your project:
- `components/ui/week-strip/week-strip.tsx`
- `components/ui/week-strip/index.ts`
Installs:
- `date-fns` ^4.4.0
- `lucide-react` ^0.552.0

## Usage
```tsx
import { useState } from "react"
import { WeekStrip } from "@/components/ui/week-strip"

export function Schedule() {
  const [day, setDay] = useState(new Date())
  return (
    <WeekStrip aria-label="Schedule" value={day} onValueChange={setDay} counts={{ "2026-11-18": 3 }}>
      <Agenda day={day} />
    </WeekStrip>
  )
}
```

## Examples

### Default
Last week to three weeks ahead, today selected.
```tsx
import { useState } from 'react';
import { startOfDay } from '@/components/ui/calendar';
import { WeekStrip } from '@/components/ui/week-strip';

export function Example() {
  const [day, setDay] = useState(() => startOfDay(new Date()));
  return <WeekStrip aria-label="Schedule" className="max-w-xl" value={day} onValueChange={setDay} />;
}
```

### Bookings
Dots for each day's bookings, and the day's list under the strip.
```tsx
import { useState } from 'react';
import { startOfDay, toISODate } from '@/components/ui/calendar';
import { WeekStrip } from '@/components/ui/week-strip';

export function Example({ bookings }: { bookings: Record<string, string[]> }) {
  const [day, setDay] = useState(() => startOfDay(new Date()));
  const counts = Object.fromEntries(Object.entries(bookings).map(([k, v]) => [k, v.length]));
  const list = bookings[toISODate(day)] ?? [];
  return (
    <WeekStrip
      aria-label="Bookings"
      className="max-w-xl"
      value={day}
      onValueChange={setDay}
      counts={counts}
      formatCount={(n) => `${n} ${n === 1 ? "booking" : "bookings"}`}
    >
      <ul className="grid gap-1 px-[1.125rem] pt-2 text-sm">
        {list.length ? list.map((v) => <li key={v}>{v}</li>) : <li className="text-muted-foreground">No bookings</li>}
      </ul>
    </WeekStrip>
  );
}
```

## Notes

### Server rendering
Pass `today` when the page renders on a server, so the server and the browser agree on which day it is.

### Phone and desktop
Below 768px the title is the screen's own: large, and Today when it is.

### Long ranges
Only the eight weeks either side of the selected one render, and more join as the strip scrolls toward an end, so a range of a year or more stays light.

## API reference
Props marked **agent** change what an agent reads or may do.

### WeekStrip
The title with Today and week steps, the row of days, and whatever the selected day shows under it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` **agent** | `Date` | - | Controlled day. Defaults to today. |
| `defaultValue` | `Date` | - | Starting day when uncontrolled. |
| `onValueChange` **agent** | `(value, details) => void` | - | Runs on every pick, for people and agents. `details.cancel()` refuses the change. |
| `min` **agent** | `Date` | `Start of last week` | The first day in the strip. |
| `max` **agent** | `Date` | `End of the third week ahead` | The last day in the strip. |
| `counts` | `Record<string, number>` | - | How busy each day is, keyed `YYYY-MM-DD`. Up to three dots show under the date. |
| `thresholds` | `[number, number, number]` | - | Counts at or above each step get one more dot. Defaults to one dot per count, up to three. |
| `formatCount` | `(count: number) => string` | `"2 events"` | How a day's count reads to screen readers. |
| `locale` | `Locale` | - | A date-fns locale for day names and the first day of the week. |
| `weekStartsOn` | `0 to 6` | `1` | The first day of the week, 0 for Sunday. Defaults to the locale's. |
| `dir` | `"ltr" \| "rtl"` | - | Reading direction. Arrow keys follow it. |
| `today` | `Date` | - | Overrides the current day. |
| `disabled` **agent** | `boolean` | `false` | Blocks people and agents. |
| `name` | `string` | - | Submits the day as `YYYY-MM-DD`. |
| `children` | `ReactNode` | - | The content under the strip, for the selected day. |

## Agent
Inside an `AgentProvider`, Week Strip appears in `agent.snapshot()` as `date`.
Reads:
- `label`: The aria-label, "Day" by default.
- `value`: The selected day as YYYY-MM-DD.
Actions:
- `setValue("2026-11-20")`: Selects a day. Phrases such as "next fri" work too.
An agent's change runs through `onValueChange` like anyone's. `isAgentChange(details)` is true for it; `details.cancel()` refuses it. A day off the strip is refused with its first or last day.
```ts
await agent.act({
  steps: [{ ref: "Schedule", action: "setValue", args: ["next fri"] }],
})
```

## Accessibility
- The days are a horizontal listbox; the selected day has aria-selected and is the only one in the tab order.
- Each day is named in full, with its count when `counts` is given, such as Wednesday 18 November, 3 events. Days in another year than today's carry the year, and so does the title.
- The title is a live region, so the selected day is announced as it changes.
### Keyboard
| Keys | Does |
| --- | --- |
| `←` / `→` | Selects the day before or after |
| `PageUp` / `PageDown` | Selects the same day a week before or after, or the first or last day when less than a week is left |
| `Home` | Goes back to today |
| `End` | Goes to the last day |

## Source
`components/ui/week-strip/week-strip.tsx`
```tsx
"use client"

import * as React from "react";
import { format, type Locale } from "date-fns";
import { ChevronLeft, ChevronRight } from "lucide-react";
import { cn } from "@/lib/utils";
import { changeAsAgent, useAgentControl, useAgentState, useHasAgent } from "@/components/ui/agent";
import {
  type CalendarChangeDetails,
  addDays,
  dayFirst,
  daysBetween,
  fromISODate,
  isSameDay,
  parseDate,
  startOfDay,
  toISODate,
} from "@/components/ui/calendar";

function changeDetails(reason: string, event?: Event): CalendarChangeDetails {
  const details: CalendarChangeDetails = {
    reason,
    event,
    isCanceled: false,
    cancel() {
      details.isCanceled = true;
    },
  };
  return details;
}

const reducedMotion = () => typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;

const startOfWeek = (d: Date, weekStartsOn: number) => addDays(d, -((d.getDay() - weekStartsOn + 7) % 7));

/** Weeks rendered either side of the selected one. */
const SPAN = 8;

const events = (n: number) => `${n} ${n === 1 ? "event" : "events"}`;

export interface WeekStripProps
  extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange" | "dir"> {
  /** The selected day. Defaults to today. */
  value?: Date;
  defaultValue?: Date;
  onValueChange?: (value: Date, details: CalendarChangeDetails) => void;
  /** The first day in the strip. Defaults to the start of last week. */
  min?: Date;
  /** The last day in the strip. Defaults to the end of the third week ahead. */
  max?: Date;
  /** How busy each day is, keyed YYYY-MM-DD. Up to three dots show under the date. */
  counts?: Record<string, number>;
  /** Counts at or above each step get one more dot. Defaults to one dot per count, up to three. */
  thresholds?: [number, number, number];
  /** How a day's count reads to screen readers. Defaults to `2 events`. */
  formatCount?: (count: number) => string;
  /** A date-fns locale, for day names and the first day of the week. */
  locale?: Locale;
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  dir?: "ltr" | "rtl";
  /** Defaults to the current day. */
  today?: Date;
  disabled?: boolean;
  /** Submits the day as YYYY-MM-DD. */
  name?: string;
  /** What the content under the strip shows for the selected day. */
  children?: React.ReactNode;
}

/**
 * Days in a row that snaps a week at a time, for schedules and bookings where the week
 * matters more than the month. The content under it follows the selected day.
 */
const WeekStrip = React.forwardRef<HTMLDivElement, WeekStripProps>((props, ref) => {
  const {
    value: valueProp,
    defaultValue,
    onValueChange,
    min: minProp,
    max: maxProp,
    counts,
    thresholds,
    formatCount = events,
    locale,
    weekStartsOn = locale?.options?.weekStartsOn ?? 1,
    dir,
    today: todayProp,
    disabled,
    name,
    className,
    children,
    "aria-label": ariaLabel = "Day",
    "aria-labelledby": labelledBy,
    ...rest
  } = props;
  const hasAgent = useHasAgent();
  const today = React.useMemo(() => startOfDay(todayProp ?? new Date()), [todayProp ? toISODate(todayProp) : null]);
  const thisWeek = startOfWeek(today, weekStartsOn);
  const min = startOfDay(minProp ?? addDays(thisWeek, -7));
  const max = startOfDay(maxProp ?? addDays(thisWeek, 27));
  const clamp = (d: Date) => (d < min ? min : d > max ? max : d);

  const [raw, change] = useAgentState<Date, CalendarChangeDetails>(valueProp, defaultValue ?? clamp(today), onValueChange);
  const value = startOfDay(raw);
  // A value off the strip still leaves a day to tab to and step from.
  const stop = clamp(value);
  const strip = React.useRef<HTMLDivElement>(null);

  /* ---- only the weeks around the stop render, and more as the strip scrolls ---- */
  const around = startOfWeek(stop, weekStartsOn);
  const near = { from: clamp(addDays(around, -7 * SPAN)), to: clamp(addDays(around, 7 * SPAN + 6)) };
  const [shown, setShown] = React.useState(() => ({ from: toISODate(near.from), to: toISODate(near.to) }));
  let from = fromISODate(shown.from)!;
  let to = fromISODate(shown.to)!;
  if (from < min || to > max || near.from < from || near.to > to) {
    const joined = near.from <= addDays(to, 1) && near.to >= addDays(from, -1);
    from = clamp(joined && from < near.from ? from : near.from);
    to = clamp(joined && to > near.to ? to : near.to);
    setShown({ from: toISODate(from), to: toISODate(to) });
  }
  const days = Array.from({ length: daysBetween(from, to) + 1 }, (_, i) => addDays(from, i));
  const widthBefore = React.useRef<number | null>(null);
  const grow = () => {
    const sc = strip.current;
    const pills = sc?.querySelectorAll<HTMLElement>("[data-day]");
    if (!sc || !pills?.length) return;
    const rtl = getComputedStyle(sc).direction === "rtl";
    const box = sc.getBoundingClientRect();
    const head = pills[0].getBoundingClientRect();
    const tail = pills[pills.length - 1].getBoundingClientRect();
    const before = rtl ? head.right - box.right : box.left - head.left;
    const after = rtl ? box.left - tail.left : tail.right - box.right;
    if (before < box.width && from > min) {
      widthBefore.current = sc.scrollWidth;
      setShown((s) => ({ ...s, from: toISODate(clamp(addDays(fromISODate(s.from)!, -7 * SPAN))) }));
    } else if (after < box.width && to < max) {
      setShown((s) => ({ ...s, to: toISODate(clamp(addDays(fromISODate(s.to)!, 7 * SPAN))) }));
    }
  };
  // Days added before the ones in view push them along; scrolling back by as much keeps them still.
  React.useLayoutEffect(() => {
    const sc = strip.current;
    if (!sc || widthBefore.current === null) return;
    const added = sc.scrollWidth - widthBefore.current;
    widthBefore.current = null;
    sc.scrollLeft += getComputedStyle(sc).direction === "rtl" ? -added : added;
  }, [shown.from]);

  const select = (d: Date, reason: string, event?: Event) => {
    if (disabled || d < min || d > max || isSameDay(d, value)) return;
    change(d, changeDetails(reason, event));
  };

  /* ---- the selected day's week stays in view ---- */
  // The day a key or Today asked for, focused once it is the value.
  const focusNext = React.useRef<string | null>(null);
  const first = React.useRef(true);
  React.useLayoutEffect(() => {
    const sc = strip.current;
    const pill = sc?.querySelector<HTMLElement>(`[data-day="${toISODate(stop)}"]`);
    const start = sc?.querySelector<HTMLElement>(`[data-day="${toISODate(clamp(startOfWeek(stop, weekStartsOn)))}"]`);
    if (!sc || !pill) return;
    if (start) {
      // Scrolls the strip only; scrollIntoView would move the page too.
      const box = sc.getBoundingClientRect();
      const at = start.getBoundingClientRect();
      const pad = parseFloat(getComputedStyle(sc).scrollPaddingInlineStart) || 0;
      const rtl = getComputedStyle(sc).direction === "rtl";
      const delta = rtl ? at.right - box.right + pad : at.left - box.left - pad;
      sc.scrollTo?.({ left: sc.scrollLeft + delta, behavior: first.current || reducedMotion() ? "auto" : "smooth" });
    }
    first.current = false;
    if (focusNext.current === toISODate(value)) pill.focus({ preventScroll: true });
    focusNext.current = null;
  }, [toISODate(value)]);

  /* ---- agent ---- */
  useAgentControl(() => ({
    kind: "date",
    element: strip.current,
    value: toISODate(value),
    disabled,
    actions: {
      setValue: (wanted: unknown) => {
        const d =
          wanted instanceof Date
            ? isNaN(wanted.getTime()) ? null : startOfDay(wanted)
            : typeof wanted === "string"
              ? fromISODate(wanted) ?? parseDate(wanted, { today, order: dayFirst(locale) ? "day-first" : "month-first", weekStartsOn })
              : null;
        if (!d) return `"${String(wanted)}" is not a date. Send YYYY-MM-DD, or a phrase such as next fri.`;
        if (d < min) return `The strip starts on ${toISODate(min)}.`;
        if (d > max) return `The strip ends on ${toISODate(max)}.`;
        return changeAsAgent((next: Date, details: CalendarChangeDetails) => {
          if (!isSameDay(next, value)) change(next, details);
        }, d);
      },
    },
  }));

  /* ---- render ---- */
  const isToday = isSameDay(value, today);
  const week = (n: -1 | 1) => clamp(addDays(stop, 7 * n));
  const otherYear = (d: Date) => d.getFullYear() !== today.getFullYear();
  const iconButton = "inline-flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40";

  return (
    <div {...rest} ref={ref} dir={dir} data-slot="week-strip" data-disabled={disabled || undefined} className={cn("w-full", className)}>
      <div data-slot="week-strip-header" className="flex items-center gap-2 px-[1.125rem] pb-3">
        <div
          data-slot="week-strip-title"
          aria-live="polite"
          className="min-w-0 flex-1 truncate text-[1.625rem] font-semibold tracking-[-0.02em] md:text-[0.9375rem] md:tracking-normal"
        >
          {/* A phone's title is the screen's own, so it is short and says Today when it is. */}
          <span className="md:hidden">{isToday ? "Today" : format(value, otherYear(value) ? "EEE d MMM yyyy" : "EEE d MMM", { locale })}</span>
          <span className="max-md:hidden">{format(value, otherYear(value) ? "EEEE d MMMM yyyy" : "EEEE d MMMM", { locale })}</span>
        </div>
        {!isToday && today >= min && today <= max && (
          <button
            type="button"
            data-slot="week-strip-today"
            data-agent-part={hasAgent ? "" : undefined}
            disabled={disabled}
            onClick={(e) => {
              focusNext.current = toISODate(today);
              select(today, "today-press", e.nativeEvent);
            }}
            className="inline-flex h-8 items-center rounded-md px-3 text-sm font-medium hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
          >
            Today
          </button>
        )}
        {([-1, 1] as const).map((n) => (
          <button
            key={n}
            type="button"
            aria-label={n < 0 ? "Previous week" : "Next week"}
            data-slot={n < 0 ? "week-strip-previous" : "week-strip-next"}
            data-agent-part={hasAgent ? "" : undefined}
            disabled={disabled || isSameDay(week(n), stop)}
            onClick={(e) => select(week(n), "week-step", e.nativeEvent)}
            className={iconButton}
          >
            {n < 0 ? <ChevronLeft className="size-4 rtl:rotate-180" aria-hidden /> : <ChevronRight className="size-4 rtl:rotate-180" aria-hidden />}
          </button>
        ))}
      </div>
      <div
        ref={strip}
        role="listbox"
        aria-orientation="horizontal"
        aria-label={ariaLabel}
        aria-labelledby={labelledBy}
        aria-disabled={disabled || undefined}
        data-slot="week-strip-days"
        className={cn(
          "flex snap-x snap-mandatory scroll-px-[1.125rem] gap-1.5 overflow-x-auto px-[1.125rem] pb-2.5 pt-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden",
          // The clipped day fades, so it reads as more to scroll rather than a cut.
          "[mask-image:linear-gradient(to_right,transparent,#000_14px,#000_calc(100%-32px),transparent)]",
          "rtl:[mask-image:linear-gradient(to_left,transparent,#000_14px,#000_calc(100%-32px),transparent)]"
        )}
        onScroll={grow}
        onKeyDown={(e) => {
          const rtl = strip.current?.closest("[dir]")?.getAttribute("dir") === "rtl";
          const step: Record<string, number> = { ArrowLeft: rtl ? 1 : -1, ArrowRight: rtl ? -1 : 1 };
          const next =
            e.key === "Home" ? clamp(today)
            : e.key === "End" ? max
            : e.key === "PageUp" ? week(-1)
            : e.key === "PageDown" ? week(1)
            : step[e.key] !== undefined ? addDays(stop, step[e.key])
            : null;
          if (!next) return;
          e.preventDefault();
          if (next < min || next > max) return;
          focusNext.current = toISODate(next);
          select(next, "keyboard", e.nativeEvent);
        }}
      >
        {days.map((d) => {
          const n = counts?.[toISODate(d)] ?? 0;
          const dots = n <= 0 ? 0 : thresholds ? thresholds.filter((t) => n >= t).length : Math.min(n, 3);
          const selected = isSameDay(d, value);
          return (
            <button
              key={toISODate(d)}
              type="button"
              role="option"
              data-slot="week-strip-day"
              data-day={toISODate(d)}
              data-today={isSameDay(d, today) || undefined}
              aria-selected={selected}
              aria-label={`${format(d, otherYear(d) ? "EEEE d MMMM yyyy" : "EEEE d MMMM", { locale })}${counts ? `, ${formatCount(n)}` : ""}`}
              tabIndex={isSameDay(d, stop) ? 0 : -1}
              disabled={disabled}
              onClick={(e) => select(d, "day-press", e.nativeEvent)}
              className={cn(
                "grid w-[2.625rem] shrink-0 snap-start justify-items-center gap-[3px] rounded-[0.875rem] border border-transparent pb-[9px] pt-2 md:w-16",
                "transition-colors duration-150 motion-reduce:transition-none hover:bg-accent",
                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
                "data-[today]:border-muted-foreground",
                "aria-selected:bg-primary aria-selected:text-primary-foreground aria-selected:hover:bg-primary",
                "disabled:pointer-events-none disabled:opacity-50",
                // A gap between weeks shows where each starts.
                d.getDay() === weekStartsOn && !isSameDay(d, from) && "ms-2.5"
              )}
            >
              <span className={cn("text-[0.6875rem] uppercase tracking-[0.04em] text-muted-foreground", selected && "text-current opacity-70")}>
                {format(d, "EEE", { locale })}
              </span>
              <span className="text-[1.0625rem] font-medium tabular-nums md:text-lg">{d.getDate()}</span>
              <span aria-hidden className="flex h-1 gap-[3px]">
                {Array.from({ length: dots }, (_, i) => (
                  <i key={i} className={cn("size-1 rounded-full bg-muted-foreground", selected && "bg-primary-foreground")} />
                ))}
              </span>
            </button>
          );
        })}
      </div>
      {children}
      {name && <input type="hidden" name={name} disabled={disabled} value={toISODate(value)} />}
    </div>
  );
});
WeekStrip.displayName = "WeekStrip";

export { WeekStrip };
```
