@lekoala/date-picker 0.1.0

package/docs/USE_CASES.md

@@ -0,0 +1,128 @@
+# Use cases
+
+These cases define the product more strongly than a feature checklist. A proposed API change should be tested against them before being accepted.
+
+## U1 — Editable localized date field
+
+A user can type `06/09/2026` in `fr-BE`, open the calendar, select the same date visually, and submit `2026-09-06` to the server.
+
+Acceptance:
+
+- input remains editable;
+- label still targets the real input;
+- required/custom validity still works;
+- display formatting does not leak into submitted data.
+
+## U2 — Inline selector
+
+An inline calendar owns one selected date.
+
+Acceptance:
+
+- month/year navigation does not change the value;
+- arrow-key focus does not change the value;
+- click/Enter/Space activates and selects;
+- today, focused and selected are visually/semantically distinct.
+
+## U3 — Mini calendar navigator
+
+An inline `selection="none"` calendar navigates a separate agenda/calendar.
+
+Acceptance:
+
+- there may be no selected value at all;
+- changing month/year only changes what the mini calendar displays;
+- activating a date dispatches `dateactivate` and the application calls `calendarView.gotoDate(date)`;
+- outside-month days remain activatable;
+- six-row height is available as presentation, not baked into month math;
+- ISO week numbers are available.
+
+## U4 — Constrained dates
+
+Example: only the next 90 days, weekdays only.
+
+Acceptance:
+
+- min/max affect both activation and typed validation;
+- custom disabled days can still receive keyboard focus so the reason can be announced;
+- disabled activation never changes the value;
+- previous/next controls stop at bounded months.
+
+## U5 — Linked start/end dates
+
+Two fields represent a range.
+
+Acceptance:
+
+- end cannot validate before start;
+- start cannot validate after end;
+- changing one side revalidates the other;
+- the component never silently rewrites the sibling value;
+- each picker remains independently usable and replaceable.
+
+## U6 — Remote availability
+
+Changing the displayed month loads per-day state from a backend.
+
+Acceptance:
+
+- load receives the actual rendered range;
+- superseded navigation aborts the previous request;
+- state can disable a day or describe it;
+- loading logic is independent of URL/backend format;
+- a typed date can call `ensureDate()` before validation.
+
+## U7 — Morning / afternoon indicators
+
+A date can carry richer state such as morning/afternoon availability.
+
+Acceptance:
+
+- the business fields remain opaque to core logic;
+- visual badges/dots live inside the owned day cell;
+- accessible meaning is supplied through `description`;
+- custom rendering cannot replace focus/ARIA semantics.
+
+## U8 — Keyboard-only operation
+
+Everything above works without a pointing device.
+
+Acceptance:
+
+- one grid cell in the Tab sequence;
+- arrows, Home/End, PageUp/PageDown, Shift+PageUp/PageDown work;
+- changing display follows keyboard focus when focus crosses a month;
+- activation requires Enter/Space;
+- Escape closes the picker and restores a sensible focus target;
+- month/year selects remain normal native controls.
+
+## U9 — Two fields, one shared calendar
+
+A form has two editable date fields (arrival/departure) that share a single calendar surface inside one picker popup.
+
+Acceptance:
+
+- each field stays independently editable and localized, with its own hidden ISO value for submission;
+- opening from a bound targets that bound: selecting a first date commits it, moves the active endpoint to the other bound without closing, and a second selection commits and closes;
+- once an ordered range is complete, activating before it extends the start and activating after it extends the end, regardless of the opening field; the opposite bound stays unchanged and readonly/disabled bounds remain protected;
+- a preloaded range shows the band on open and is never reordered;
+- month/year navigation and arrow-key focus never mutate either bound;
+- an inverted range (start after end) keeps both entered values and surfaces an order error on the bound that was just modified; changing either side revalidates both;
+- form reset restores both fields in one resync;
+- a stale async availability response arriving after the active endpoint changed never commits a value or closes the popup;
+- only the bounds are validated; per-night availability stays application-owned.
+
+## Not a use case for this package
+
+Do not grow the API to cover these without a separate design:
+
+- time slots;
+- duration picking;
+- timezone conversion;
+- appointment recurrence;
+- resource scheduling;
+- drag/drop;
+- event rendering;
+- multi-day scheduler views.
+
+Those belong to `@lekoala/calendar` or application logic.

package/package.json

@@ -0,0 +1,174 @@
+{
+  "name": "@lekoala/date-picker",
+  "version": "0.1.0",
+  "description": "Native-first date picker and inline calendar primitives",
+  "type": "module",
+  "sideEffects": [
+    "./src/define.js",
+    "./src/date-picker.css",
+    "./dist/date-picker.js",
+    "./dist/date-picker.min.js",
+    "./dist/date-picker.standalone.min.js",
+    "./dist/date-picker.css",
+    "./dist/date-picker.min.css"
+  ],
+  "license": "MIT",
+  "customElements": "custom-elements.json",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lekoala/date-picker.git"
+  },
+  "homepage": "https://github.com/lekoala/date-picker",
+  "bugs": "https://github.com/lekoala/date-picker/issues",
+  "packageManager": "bun@1.4.2",
+  "keywords": [
+    "date-picker",
+    "calendar",
+    "datepicker",
+    "popover",
+    "web-component",
+    "accessibility"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "custom-elements.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./define": {
+      "types": "./dist/types/define.d.ts",
+      "import": "./src/define.js"
+    },
+    "./calendar": {
+      "types": "./dist/types/date-calendar.d.ts",
+      "import": "./src/date-calendar.js"
+    },
+    "./date-picker.css": "./src/date-picker.css",
+    "./locales/ar": {
+      "types": "./dist/types/locales/ar.d.ts",
+      "import": "./src/locales/ar.js"
+    },
+    "./locales/de": {
+      "types": "./dist/types/locales/de.d.ts",
+      "import": "./src/locales/de.js"
+    },
+    "./locales/en": {
+      "types": "./dist/types/locales/en.d.ts",
+      "import": "./src/locales/en.js"
+    },
+    "./locales/es": {
+      "types": "./dist/types/locales/es.d.ts",
+      "import": "./src/locales/es.js"
+    },
+    "./locales/fr": {
+      "types": "./dist/types/locales/fr.d.ts",
+      "import": "./src/locales/fr.js"
+    },
+    "./locales/hi": {
+      "types": "./dist/types/locales/hi.d.ts",
+      "import": "./src/locales/hi.js"
+    },
+    "./locales/id": {
+      "types": "./dist/types/locales/id.d.ts",
+      "import": "./src/locales/id.js"
+    },
+    "./locales/it": {
+      "types": "./dist/types/locales/it.d.ts",
+      "import": "./src/locales/it.js"
+    },
+    "./locales/ja": {
+      "types": "./dist/types/locales/ja.d.ts",
+      "import": "./src/locales/ja.js"
+    },
+    "./locales/ko": {
+      "types": "./dist/types/locales/ko.d.ts",
+      "import": "./src/locales/ko.js"
+    },
+    "./locales/nl": {
+      "types": "./dist/types/locales/nl.d.ts",
+      "import": "./src/locales/nl.js"
+    },
+    "./locales/pl": {
+      "types": "./dist/types/locales/pl.d.ts",
+      "import": "./src/locales/pl.js"
+    },
+    "./locales/pt-BR": {
+      "types": "./dist/types/locales/pt-BR.d.ts",
+      "import": "./src/locales/pt-BR.js"
+    },
+    "./locales/pt-PT": {
+      "types": "./dist/types/locales/pt-PT.d.ts",
+      "import": "./src/locales/pt-PT.js"
+    },
+    "./locales/ru": {
+      "types": "./dist/types/locales/ru.d.ts",
+      "import": "./src/locales/ru.js"
+    },
+    "./locales/tr": {
+      "types": "./dist/types/locales/tr.d.ts",
+      "import": "./src/locales/tr.js"
+    },
+    "./locales/zh-CN": {
+      "types": "./dist/types/locales/zh-CN.d.ts",
+      "import": "./src/locales/zh-CN.js"
+    },
+    "./standalone": "./dist/date-picker.standalone.min.js",
+    "./dist/date-picker.js": "./dist/date-picker.js",
+    "./dist/date-picker.min.js": "./dist/date-picker.min.js",
+    "./dist/date-picker.standalone.min.js": "./dist/date-picker.standalone.min.js",
+    "./dist/date-picker.css": "./dist/date-picker.css",
+    "./dist/date-picker.min.css": "./dist/date-picker.min.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "node test/server.js",
+    "dev:kill": "node scripts/kill-port.mjs",
+    "dev:restart": "node scripts/kill-port.mjs && node test/server.js",
+    "build:bundle": "bun scripts/build.js",
+    "build:types": "bun run types",
+    "build:manifest": "bun scripts/custom-elements.js",
+    "build": "bun run build:bundle && bun run build:types && bun run build:manifest",
+    "sync": "bun run build",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc -p jsconfig.json",
+    "types": "tsc -p tsconfig.types.json",
+    "test": "bun test test/unit",
+    "test:syntax": "node --check src/date.js && node --check src/intl.js && node --check src/calendar-model.js && node --check src/source.js && node --check src/messages.js && node --check src/date-calendar.js && node --check src/date-field.js && node --check src/date-picker.js && node --check src/date-range.js && node --check src/index.js && node --check src/define.js",
+    "test:types": "tsc -p test/types/tsconfig.json",
+    "test:browser": "playwright test browser --project chromium",
+    "test:browser:accessibility": "playwright test test/browser/picker.spec.js test/browser/focus.spec.js test/browser/calendar.spec.js test/browser/form-state.spec.js test/browser/surfaces.spec.js",
+    "test:browser:headed": "playwright test browser --project chromium --headed",
+    "test:browser:all": "playwright test browser",
+    "test:dist": "playwright test dist --project chromium",
+    "shot:forced-colors": "bun scripts/forced-colors-shot.js",
+    "shot:forced-colors:important": "bun scripts/forced-colors-shot.js /demo/index.html --scenario important --out-dir tmp/forced-colors-important",
+    "shot:forced-colors:important:dark": "bun scripts/forced-colors-shot.js /demo/index.html --scheme dark --scenario important --out-dir tmp/forced-colors-important-dark",
+    "check": "bun run test:syntax && bun run lint && bun run typecheck && bun run test",
+    "verify": "bun run check && bun run sync && bun run test:types && bun run check:generated && bun run check:package",
+    "check:all": "bun run verify && bun run test:browser:all && bun run test:dist",
+    "check:generated": "bun scripts/check-generated.js",
+    "check:package": "bun scripts/check-package.js",
+    "prepack": "bun run sync",
+    "prepublishOnly": "bun run verify"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.11",
+    "@lekoala/calendar": "0.1.0",
+    "@playwright/test": "1.62.1",
+    "temporal-polyfill": "^1.0.4",
+    "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "@lekoala/floating": "^0.1.1"
+  }
+}

package/src/calendar-model.js

@@ -0,0 +1,80 @@
+import {
+  addDays,
+  addMonths,
+  addYears,
+  endOfWeek,
+  isDate,
+  monthKey,
+  shiftMonth,
+  startOfWeek,
+  todayISO,
+} from "./date.js";
+
+export class CalendarModel {
+  /**
+   * @param {{value?:string, display?:string, focused?:string, firstDay?:number}} [options]
+   */
+  constructor(options = {}) {
+    const today = todayISO();
+    this.firstDay = options.firstDay ?? 1;
+    this.value = options.value && isDate(options.value) ? options.value : "";
+    this.focused = options.focused && isDate(options.focused) ? options.focused : this.value || today;
+    this.display = options.display ? monthKey(options.display) : monthKey(this.focused);
+  }
+
+  /** @param {string} value */
+  setValue(value) {
+    if (value && !isDate(value)) throw new TypeError(`Invalid value: ${value}`);
+    this.value = value || "";
+    return this.value;
+  }
+
+  /** @param {string} value */
+  setDisplay(value) {
+    const target = monthKey(value);
+    const day = Number(this.focused.slice(8, 10)) || 1;
+    const next = addMonths(`${target}-01`, 0);
+    const candidate = addDays(next, Math.max(0, day - 1));
+    this.focused = monthKey(candidate) === target ? candidate : addDays(`${shiftMonth(target, 1)}-01`, -1);
+    this.display = target;
+    return this.display;
+  }
+
+  /** @param {string} value @param {{follow?:boolean}} [options] */
+  setFocused(value, options = {}) {
+    if (!isDate(value)) throw new TypeError(`Invalid focused date: ${value}`);
+    this.focused = value;
+    if (options.follow !== false) this.display = monthKey(value);
+    return this.focused;
+  }
+
+  /** @param {number} amount */
+  moveFocusDays(amount) {
+    return this.setFocused(addDays(this.focused, amount));
+  }
+
+  /** @param {number} amount */
+  moveFocusMonths(amount) {
+    return this.setFocused(addMonths(this.focused, amount));
+  }
+
+  /** @param {number} amount */
+  moveFocusYears(amount) {
+    return this.setFocused(addYears(this.focused, amount));
+  }
+
+  focusWeekStart() {
+    return this.setFocused(startOfWeek(this.focused, this.firstDay));
+  }
+
+  focusWeekEnd() {
+    return this.setFocused(endOfWeek(this.focused, this.firstDay));
+  }
+
+  /** Header/month-select navigation. Value is intentionally untouched. @param {number} amount */
+  navigateMonth(amount) {
+    const target = shiftMonth(this.display, amount);
+    this.setDisplay(target);
+    return this.display;
+  }
+}