@lekoala/slot-picker 0.1.0

package/src/source.js

@@ -0,0 +1,87 @@
+/** @typedef {{start:string,end:string,dayCount:number,signal:AbortSignal}} SourceContext */
+/** @typedef {{after:string,signal:AbortSignal}} NextContext */
+/** @typedef {(context:SourceContext) => Promise<unknown>|unknown} SlotSourceFunction */
+/** @typedef {{load:(context:SourceContext) => Promise<unknown>|unknown, next?:(context:NextContext) => Promise<string|null|undefined>|string|null|undefined}} SlotSourceObject */
+/** @typedef {SlotSourceFunction|SlotSourceObject} SlotSource */
+
+export class SlotSourceController {
+  /** @type {SlotSource|null} */
+  #source = null;
+  /** @type {AbortController|null} */
+  #controller = null;
+  /** @type {AbortController|null} */
+  #nextController = null;
+  #request = 0;
+  #nextRequest = 0;
+
+  /** @param {SlotSource|null} source */
+  set source(source) {
+    const isFunction = typeof source === "function";
+    const isObject = source !== null && typeof source === "object" && typeof source.load === "function";
+    if (source !== null && !isFunction && !isObject) {
+      throw new TypeError("source must be a function or an object with a load() method");
+    }
+    this.abort();
+    this.#source = source;
+  }
+
+  get source() {
+    return this.#source;
+  }
+
+  /** Whether the current source can resolve a date beyond the visible range. */
+  get hasNext() {
+    const source = this.#source;
+    return Boolean(source && typeof source === "object" && typeof source.next === "function");
+  }
+
+  abort() {
+    this.#controller?.abort();
+    this.#controller = null;
+    this.#nextController?.abort();
+    this.#nextController = null;
+  }
+
+  /** @param {{start:string,end:string,dayCount:number}} range */
+  async load(range) {
+    const source = this.#source;
+    if (!source) return null;
+    const loader = typeof source === "function" ? source : source.load;
+
+    this.abort();
+    const controller = new AbortController();
+    this.#controller = controller;
+    const request = ++this.#request;
+
+    try {
+      const result = await loader({ ...range, signal: controller.signal });
+      if (request !== this.#request || controller.signal.aborted) return null;
+      return result;
+    } finally {
+      if (this.#controller === controller) this.#controller = null;
+    }
+  }
+
+  /**
+   * Ask the source for the next known availability after `after`.
+   * Superseded calls are aborted; a stale response resolves to null.
+   * @param {{after:string}} context
+   */
+  async next({ after }) {
+    const source = this.#source;
+    if (!source || typeof source !== "object" || typeof source.next !== "function") return null;
+
+    this.#nextController?.abort();
+    const controller = new AbortController();
+    this.#nextController = controller;
+    const request = ++this.#nextRequest;
+
+    try {
+      const result = await source.next({ after, signal: controller.signal });
+      if (request !== this.#nextRequest || controller.signal.aborted) return null;
+      return typeof result === "string" ? result : null;
+    } finally {
+      if (this.#nextController === controller) this.#nextController = null;
+    }
+  }
+}

package/src/views/columns.js

@@ -0,0 +1,108 @@
+import { toUtcDate } from "../date.js";
+import { collapsedDays, slotValue } from "../model.js";
+import {
+  dayEmpty,
+  enabledValues,
+  escapeAttr,
+  escapeHtml,
+  noticeBlock,
+  noticeIndicator,
+  rovingValue,
+  slotButton,
+} from "./shared.js";
+
+const UTC_FORMAT = { timeZone: "UTC" };
+
+/** @typedef {import("../model.js").SlotDay} SlotDay */
+/** @typedef {import("./shared.js").SlotCountMessages & {empty:string,closed:string}} ColumnsMessages */
+
+/**
+ * Columns projection: N civil days side by side with their slots.
+ * Empty days render a real DOM empty state (messages.empty); alignment
+ * placeholders are aria-hidden and only used when the day has slots
+ * but fewer rows than the visible grid.
+ * @param {{visible:SlotDay[],value:string,focusedValue:string,maxVisibleRows:number,expanded:boolean,noticeDisplay:"inline"|"action"|"none",messages:ColumnsMessages,locale:string}} options
+ */
+export function renderColumns({
+  visible,
+  value,
+  focusedValue,
+  maxVisibleRows,
+  expanded,
+  noticeDisplay,
+  messages,
+  locale,
+}) {
+  const formatterDay = new Intl.DateTimeFormat(locale, { weekday: "short", ...UTC_FORMAT });
+  const formatterDate = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", ...UTC_FORMAT });
+  // Collapse before computing roving focus: the single tabbable value must be
+  // one of the rendered buttons, never a slot hidden by the visible row limit.
+  const { days: collapsed, rows, hasOverflow } = collapsedDays(visible, maxVisibleRows, expanded);
+
+  const enabled = enabledValues(collapsed);
+  const firstEnabled = enabled[0] || "";
+  const activeFocus = rovingValue(enabled, focusedValue, value, firstEnabled);
+
+  const html = collapsed
+    .map(
+      /** @param {SlotDay} day @param {number} dayIndex */ (day, dayIndex) => {
+        const date = toUtcDate(day.date);
+        const weekday = formatterDay.format(date);
+        const displayDate = formatterDate.format(date);
+        const inline = noticeDisplay === "inline";
+        const action = noticeDisplay === "action";
+        // The dot is the only control (when the notice is projected at all).
+        // `inline` additionally renders the readable block, which never
+        // activates anything.
+        const headerNotice =
+          day.notice && (inline || action)
+            ? noticeIndicator({ interactive: true, dayIndex, ...day.notice })
+            : "";
+        const noticeContent = day.notice && inline ? noticeBlock(day.notice) : "";
+        const closed = Boolean(day.closed);
+
+        let body;
+        if (day.slots.length === 0) {
+          // "Closed" is a day state, distinct from "open but no availability".
+          body = `${noticeContent}${dayEmpty(closed ? messages.closed : messages.empty)}`;
+        } else {
+          const slots = day.slots;
+          const slotMarkup = slots
+            .map(
+              /** @param {import("../model.js").Slot} slot @param {number} slotIndex */ (slot, slotIndex) => {
+                const slotVal = slotValue(day.date, slot.start);
+                return slotButton({
+                  date: day.date,
+                  slot,
+                  dayIndex,
+                  slotIndex,
+                  selected: slotVal === value,
+                  tabbed: slotVal === activeFocus && !slot.disabled,
+                });
+              },
+            )
+            .join("");
+          const empties = Array.from(
+            { length: Math.max(0, rows - slots.length) },
+            () => '<span class="sp-empty" aria-hidden="true">–</span>',
+          ).join("");
+          body = `${noticeContent}<div class="sp-slots" role="listbox" aria-label="${escapeAttr(`${weekday} ${displayDate}`)}">${slotMarkup}${empties}</div>`;
+        }
+
+        return `<section class="sp-day" data-date="${escapeAttr(day.date)}"${closed ? " data-closed" : ""}>
+        <header class="sp-day-header">
+          <span class="sp-weekday">${escapeHtml(weekday)}</span>
+          <strong class="sp-date">${escapeHtml(displayDate)}</strong>
+          ${headerNotice}
+        </header>
+        ${body}
+      </section>`;
+      },
+    )
+    .join("");
+
+  return {
+    html: `<div class="sp-grid" role="presentation">${html}</div>`,
+    hasOverflow,
+  };
+}

package/src/views/day.js

@@ -0,0 +1,122 @@
+import { toUtcDate } from "../date.js";
+import { slotValue } from "../model.js";
+import {
+  dayEmpty,
+  escapeAttr,
+  escapeHtml,
+  noticeBlock,
+  noticeIndicator,
+  rovingValue,
+  slotButton,
+  slotCountText,
+} from "./shared.js";
+
+const UTC_FORMAT = { timeZone: "UTC" };
+
+/** @typedef {import("../model.js").SlotDay} SlotDay */
+/** @typedef {import("./shared.js").SlotCountMessages & {empty:string,closed:string,days:string}} DayMessages */
+
+/**
+ * Day projection: a strip of days plus the slots of the consulted day.
+ * The strip uses aria-pressed (consulted day), never aria-current="date".
+ * Today stays independently discoverable via data-today.
+ * @param {{visible:SlotDay[],activeDate:string,today:string,value:string,focusedValue:string,noticeDisplay:"inline"|"action"|"none",messages:DayMessages,locale:string}} options
+ */
+export function renderDay({
+  visible,
+  activeDate,
+  today,
+  value,
+  focusedValue,
+  noticeDisplay,
+  messages,
+  locale,
+}) {
+  const formatterStripDay = new Intl.DateTimeFormat(locale, { weekday: "short", ...UTC_FORMAT });
+  const formatterStripDate = new Intl.DateTimeFormat(locale, {
+    day: "numeric",
+    month: "short",
+    ...UTC_FORMAT,
+  });
+  const formatterPanelDay = new Intl.DateTimeFormat(locale, {
+    weekday: "long",
+    day: "numeric",
+    month: "long",
+    ...UTC_FORMAT,
+  });
+
+  const activeIndex = Math.max(
+    0,
+    visible.findIndex((day) => day.date === activeDate),
+  );
+  const active = visible[activeIndex];
+
+  const strip = visible
+    .map(
+      /** @param {SlotDay} day @param {number} dayIndex */ (day, dayIndex) => {
+        const date = toUtcDate(day.date);
+        const pressed = day.date === active.date;
+        const isToday = day.date === today;
+        const closed = Boolean(day.closed);
+        const count = closed ? messages.closed : slotCountText(day.slots.length, messages);
+        return `<button type="button" class="sp-strip-day" data-date="${escapeAttr(day.date)}" data-day-index="${dayIndex}" aria-pressed="${pressed ? "true" : "false"}"${isToday ? " data-today" : ""}${closed ? " data-closed" : ""} tabindex="${pressed ? 0 : -1}">
+        <span class="sp-strip-weekday">${escapeHtml(formatterStripDay.format(date))}</span>
+        <strong class="sp-strip-date">${escapeHtml(formatterStripDate.format(date))}</strong>
+        <span class="sp-strip-count" aria-hidden="true">${escapeHtml(count)}</span>
+        <span class="sp-visually-hidden">${escapeHtml(`${formatterPanelDay.format(date)}: ${count}`)}</span>
+      </button>`;
+      },
+    )
+    .join("");
+
+  const enabled = active.slots
+    .filter(/** @param {import("../model.js").Slot} slot */ (slot) => !slot.disabled)
+    .map(/** @param {import("../model.js").Slot} slot */ (slot) => slotValue(active.date, slot.start));
+  const firstEnabled = enabled[0] || "";
+  const activeFocus = rovingValue(enabled, focusedValue, value, firstEnabled);
+
+  // `inline` reveals the full notice here (non-interactive text); `action`
+  // keeps the single control in the panel header; `none` renders nothing.
+  const inline = noticeDisplay === "inline";
+  const notice = active.notice && inline ? noticeBlock(active.notice) : "";
+  const headerNotice =
+    active.notice && noticeDisplay === "action"
+      ? noticeIndicator({ interactive: true, dayIndex: activeIndex, ...active.notice })
+      : "";
+  const panelLabel = formatterPanelDay.format(toUtcDate(active.date));
+
+  const activeClosed = Boolean(active.closed);
+
+  let panelBody;
+  if (active.slots.length === 0) {
+    panelBody = `${notice}${dayEmpty(activeClosed ? messages.closed : messages.empty)}`;
+  } else {
+    const slots = active.slots
+      .map(
+        /** @param {import("../model.js").Slot} slot @param {number} slotIndex */ (slot, slotIndex) => {
+          const slotVal = slotValue(active.date, slot.start);
+          return slotButton({
+            date: active.date,
+            slot,
+            dayIndex: activeIndex,
+            slotIndex,
+            selected: slotVal === value,
+            tabbed: slotVal === activeFocus && !slot.disabled,
+          });
+        },
+      )
+      .join("");
+    panelBody = `${notice}<div class="sp-panel-slots" role="listbox" aria-label="${escapeAttr(panelLabel)}">${slots}</div>`;
+  }
+
+  const html = `<div class="sp-daystrip" role="group" aria-label="${escapeAttr(messages.days)}">${strip}</div>
+    <section class="sp-panel" data-date="${escapeAttr(active.date)}"${activeClosed ? " data-closed" : ""}>
+      <header class="sp-panel-header">
+        <strong class="sp-panel-title">${escapeHtml(panelLabel)}</strong>
+        ${headerNotice}
+      </header>
+      ${panelBody}
+    </section>`;
+
+  return { html };
+}

package/src/views/shared.js

@@ -0,0 +1,157 @@
+import { toUtcDate } from "../date.js";
+import { slotValue } from "../model.js";
+
+/** @typedef {import("../model.js").Slot} Slot */
+/** @typedef {{oneSlot:string,manySlots:string}} SlotCountMessages */
+/** @typedef {{rangeEmptyTitle:string,rangeEmptyDescription:string,rangeEmptyNext:string,nextAvailability:string,closedRange:string}} RangeEmptyMessages */
+
+/** @type {Record<string,string>} */
+const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+
+/** @param {string} value */
+export function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, /** @param {string} char */ (char) => ENTITIES[char] || char);
+}
+
+/** @param {string} value */
+export function escapeAttr(value) {
+  return escapeHtml(value);
+}
+
+/**
+ * Ordered values of enabled slots only. Disabled slots stay discoverable
+ * in the DOM but never take the roving tabindex.
+ * @param {{date:string,slots:Slot[]}[]} days
+ */
+export function enabledValues(days) {
+  /** @type {string[]} */
+  const values = [];
+  for (const day of days) {
+    for (const slot of day.slots) {
+      if (!slot.disabled) values.push(slotValue(day.date, slot.start));
+    }
+  }
+  return values;
+}
+
+/**
+ * Pick the single roving value: first preferred value that is enabled,
+ * otherwise the first enabled value, otherwise "".
+ * @param {string[]} enabled
+ * @param {...string} preferred
+ */
+export function rovingValue(enabled, ...preferred) {
+  for (const value of preferred) {
+    if (value && enabled.includes(value)) return value;
+  }
+  return enabled[0] || "";
+}
+
+/**
+ * Single slot button. Semantics must stay identical across projections.
+ * @param {{date:string,slot:Slot,dayIndex:number,slotIndex:number,selected:boolean,tabbed:boolean}} options
+ */
+export function slotButton({ date, slot, dayIndex, slotIndex, selected, tabbed }) {
+  const value = slotValue(date, slot.start);
+  const description = slot.description ? ` aria-description="${escapeAttr(slot.description)}"` : "";
+  // `option` backs the `aria-selected` contract: browsers ignore selection on
+  // a plain button role. The element stays a real <button> with native
+  // activation; `aria-disabled` keeps a disabled slot discoverable.
+  const disabled = slot.disabled ? ' disabled aria-disabled="true"' : "";
+  // Neutral presentation hook: a theme maps tones to color, the core does not.
+  const tone = slot.tone ? ` data-tone="${escapeAttr(slot.tone)}"` : "";
+  return `<button type="button" role="option" class="sp-slot" data-day-index="${dayIndex}" data-slot-index="${slotIndex}" data-value="${escapeAttr(value)}"${tone} aria-selected="${selected ? "true" : "false"}" tabindex="${tabbed ? 0 : -1}"${disabled}${description}>${escapeHtml(slot.start)}</button>`;
+}
+
+/**
+ * Per-day notice indicator. Without options it is purely decorative. With
+ * `interactive: true` it is the only control that emits `noticeactivate`:
+ * the accessible name carries the description, the native `title` is a
+ * desktop-only bonus.
+ * @param {{interactive?:boolean,dayIndex?:number,label?:string,description?:string}} [options]
+ */
+export function noticeIndicator(options = {}) {
+  if (options.interactive) {
+    const accessible = options.description || options.label || "";
+    const title = options.label ? ` title="${escapeAttr(options.label)}"` : "";
+    return `<button type="button" class="sp-notice" data-day-index="${options.dayIndex ?? 0}" aria-label="${escapeAttr(accessible)}"${title}><span class="sp-notice-dot" aria-hidden="true"></span></button>`;
+  }
+  return '<span class="sp-notice" aria-hidden="true"><span class="sp-notice-dot"></span></span>';
+}
+
+/**
+ * Readable day notice. Deliberately non-interactive: `noticeactivate` belongs
+ * to the explicit control, never to displayed text, so there is no mouse-only
+ * activation.
+ * @param {{label:string,description?:string}} notice
+ */
+export function noticeBlock({ label, description }) {
+  const body = `<strong class="sp-day-notice-label">${escapeHtml(label)}</strong>${
+    description ? `<span class="sp-day-notice-description">${escapeHtml(description)}</span>` : ""
+  }`;
+  return `<div class="sp-day-notice">${body}</div>`;
+}
+
+/**
+ * Real DOM empty state. Text comes from messages, never from CSS.
+ * @param {string} message
+ */
+export function dayEmpty(message) {
+  return `<div class="sp-day-empty">${escapeHtml(message)}</div>`;
+}
+
+/**
+ * Localized slot count for the day strip. Zero renders as an en dash,
+ * keeping the indicator distinct from a real sentence.
+ * @param {number} count
+ * @param {SlotCountMessages} messages
+ */
+export function slotCountText(count, messages) {
+  if (count <= 0) return "–";
+  if (count === 1) return messages.oneSlot;
+  return messages.manySlots.replace("{n}", String(count));
+}
+
+/**
+ * Range-level empty state, distinct from per-day empty days.
+ * Rendered only when the whole window has no slot and no notice; the theme
+ * decides how prominent it is. Two actions stay distinct: `next()` moves to
+ * the immediately following window, while `next availability` (opt-in via
+ * `next-availability`) is the contextual business search that may skip
+ * several windows through the source. They are never merged.
+ * @param {{start:string,end:string,invalid:boolean,canNext:boolean,nextAvailability:boolean,closed:boolean,locale:string,messages:RangeEmptyMessages}} options
+ */
+export function rangeEmpty({ start, end, invalid, canNext, nextAvailability, closed, locale, messages }) {
+  const showDescription = !invalid && Boolean(start);
+  let description = "";
+  if (showDescription) {
+    const formatter = new Intl.DateTimeFormat(locale, {
+      day: "numeric",
+      month: "short",
+      timeZone: "UTC",
+    });
+    const text = messages.rangeEmptyDescription
+      .replace("{start}", formatter.format(toUtcDate(start)))
+      .replace("{end}", formatter.format(toUtcDate(end)));
+    description = `<p class="sp-range-empty-description">${escapeHtml(text)}</p>`;
+  }
+  const actions = [];
+  if (canNext) {
+    actions.push(
+      `<button type="button" class="sp-range-empty-next">${escapeHtml(messages.rangeEmptyNext)}</button>`,
+    );
+  }
+  if (nextAvailability && !invalid) {
+    actions.push(
+      `<button type="button" class="sp-range-empty-availability">${escapeHtml(messages.nextAvailability)}</button>`,
+    );
+  }
+  const action = actions.length ? `<div class="sp-range-empty-actions">${actions.join("")}</div>` : "";
+  // A wholly closed civil range is not the same statement as "no availability".
+  const title = closed ? messages.closedRange : messages.rangeEmptyTitle;
+  return `<div class="sp-range-empty">
+    <strong class="sp-range-empty-title">${escapeHtml(title)}</strong>
+    ${description}
+    ${action}
+  </div>`;
+}