@medalsocial/booking 0.0.0-placeholder.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @medalsocial/booking
+
+## 0.1.0
+
+### Minor Changes
+
+- [#174](https://github.com/Medal-Social/MedalSocial-SDK/pull/174) [`3f5475e`](https://github.com/Medal-Social/MedalSocial-SDK/commit/3f5475e6c667e9de0c625331e050cb2f8c790f3a) Thanks [@alioftech](https://github.com/alioftech)! - New package `@medalsocial/booking` (0.1.0): a complete, themeable booking product for Medal customer sites.
+  
+  - `@medalsocial/booking/core` — the booking wizard's state machine and rules, the business's clock, money and phone formatting, service categories, age, party seating, deep links, Medal DTO mapping, ICS export, browser stores and customer-portal helpers, all driven by one validated, client-safe `BookingConfig` (`resolveBookingConfig`).
+  - `@medalsocial/booking/react` — `<BookingWizard>` (on the headless `useBooking()`), `<ManageBooking>`, `<PortalDashboard>`, `<LoginSheet>`, `<BookingLink>` and `<BookingProvider>`, composed from `@medalsocial/meda/booking` screens; server-safe label packs in `/react/shared`. A booking page imports from `@medalsocial/booking/react/wizard` (the wizard, `useBooking()`, the provider and the login sheet, without the manage page or the portal) and its layout from `@medalsocial/booking/react/link` (`<BookingLink>`, `<BookingPendingHost>`, `useNextFree()`); the build is one module per source module with `"sideEffects": false`.
+  - Labels: every key takes a `BookingLabel`, a string (one text node once filled) or an array of strings (one text node per element), so a site decides where each sentence breaks into text nodes; `fill`, `fillParts`, `labelText` and `isBookingLabel` in `/core`. The built-in packs are strings except `wizard.progress`, `wizard.slotsUnavailable.call` and `portal.greeting`; `wizard.party.sizeWord.*` spells the party size for meda's `{sizeWord}`.
+  - `@medalsocial/booking/next` — `createBookingServer()`: one route handler for every booking and portal API route, page loaders, portal action functions, and cache adapters (`/next/cache/workers`, `/next/cache/next-data`, `/next/cache/memory`, `/next/cache/noop`). The stylist-photo proxy fetches only from `avatarHosts` (default `DEFAULT_AVATAR_HOSTS`) and relays only raster images; a Vipps login grant is exchanged only in the browser that started the login.
+  
+  Pre-1.0: a minor bump may break in 0.x; pin the exact version.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023-2026 Medal Social
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+Medal Social
+https://medal.tv
+
+Copyright 2023-2026 Medal Social
+
+This product includes software developed at Medal Social.

package/README.md

@@ -1,3 +1,222 @@
 # @medalsocial/booking
 
-Placeholder that reserves the name so npm trusted publishing can be configured. The real package starts at 0.1.0 and is published from [MedalSocial-SDK](https://github.com/Medal-Social/MedalSocial-SDK) `packages/booking`.
+The booking product behind a Medal Social booking site: the wizard's rules,
+the business's clock, money, phone and deep-link handling, browser stores,
+and the customer-portal helpers — built on [`@medalsocial/sdk`](../sdk).
+
+> **Status: pre-release (0.x, not yet published).** `/core`, `/react` and
+> `/next` are in place for the first release, `0.1.0`. In 0.x a minor version
+> may break; pin the exact version.
+
+## Entry points
+
+| Import | What it is | Runs in |
+|---|---|---|
+| `@medalsocial/booking/core` | Config, wizard state machine, clock, money, phone, categories, age, party seating, deep links, DTO mapping, ICS, browser stores, portal pure helpers | Browser, Node, Workers — no React, no Next, no DOM at import time |
+| `@medalsocial/booking/react` | `<BookingWizard>` and the headless `useBooking()`, `<ManageBooking>`, `<PortalDashboard>`, `<LoginSheet>`, `<LoginFromQuery>`, `<BookingLink>`, `useNextFree()`, `<BookingProvider>` — composed from `@medalsocial/meda/booking` | Client components (`'use client'`) |
+| `@medalsocial/booking/react/wizard` | The booking page's entry: `<BookingWizard>`, `useBooking()`, `<BookingProvider>`, `<LoginSheet>` — and none of the manage page or the portal. Import a booking page from here | Client components (`'use client'`) |
+| `@medalsocial/booking/react/link` | What a layout mounts outside the booking page: `<BookingLink>`, `<BookingPendingHost>`, `useNextFree()`, `<BookingProvider>`. A root layout renders on the booking page too, so import it from here | Client components (`'use client'`) |
+| `@medalsocial/booking/react/shared` | The label packs (`BOOKING_LABELS`, `mergeLabels`) and the portal's URL/cookie readers (`parsePortalTab`, …) | Server Components and the browser — no React |
+| `@medalsocial/booking/next` | `createBookingServer`: one handler for every booking and portal API route, the page loaders (`loadBookingPage`, `loadManagePage`, `loadPortalPage`), portal session and action functions, the Medal seam | Server only (`server-only`), Next ≥ 16.3 |
+| `@medalsocial/booking/next/cache/{workers,memory,next-data,noop}` | Cache adapters: Workers Cache API, in-process LRU, Next's data cache, none | Server only |
+
+ESM only, one built module per source module, `"sideEffects": false`, so a
+bundler keeps only the modules a page reaches. A bundler keeps a `'use client'`
+entry whole, though (Turbopack does), so `/react` brings everything it exports
+to the page that imports it: use `/react/wizard` on a booking page and
+`/react/link` in the layout around it, and keep `/react` for pages where size
+does not matter.
+
+Peer dependencies: `zod` 4, `react`/`react-dom` 19 (for `/react`),
+and optionally `next` ≥ 16.3, `@medalsocial/meda` ^3.2 and `lucide-react` (all
+three needed by `/react`).
+
+## Configuration
+
+Everything a site tells the package goes through one client-safe object.
+`resolveBookingConfig` fills the defaults, validates with zod and freezes the
+result; every factory takes the resolved config.
+
+```ts
+import { createClock, createWizard, resolveBookingConfig } from '@medalsocial/booking/core';
+
+export const bookingConfig = resolveBookingConfig({
+  timeZone: 'Europe/Oslo', // required
+  locale: 'nb-NO',
+  currency: 'NOK',
+  contact: { name: 'Salong Demo', phone: '22 33 44 55', address: null },
+  categories: [
+    { key: 'barn', audience: 'child', adultEquivalent: [{ nameIncludes: 'gutt', category: 'herre' }] },
+    { key: 'herre', audience: 'adult' },
+    { key: 'annet', audience: 'any' },
+  ],
+  fallbackCategory: 'annet',
+  storageNamespace: 'salong-demo',
+});
+
+const wizard = createWizard(bookingConfig);
+const clock = createClock(bookingConfig);
+clock.when(Date.now()); // «i dag 14:15», on the business's clock
+```
+
+`BookingConfig` never holds a secret: it is serialised into the page. The
+Medal API key, cache adapters and session secret belong to the server options
+of `/next`, which read no environment variable themselves — the site passes
+its own values in.
+
+| Field | Default | Purpose |
+|---|---|---|
+| `timeZone` | — (required) | IANA zone of the business's opening hours; every clock face uses it |
+| `locale` | `nb-NO` | `Intl` formatting and the built-in label pack (`nb` or `en`) |
+| `currency` | `NOK` | ISO 4217; amounts stay in minor units on the wire |
+| `phone` | `{ country: 'NO', validate: 'strict' }` | `NO` is the only strict rule set in 0.x |
+| `paths` | `/bestill`, `/bestill/administrer`, `/min-side`, `/api/booking`, … | The URLs the site serves |
+| `query` / `whoValues` | `kategori`, `tjeneste`, `frisor`, `antall`, `hvem`, … | Deep-link query keys and values |
+| `categories` / `fallbackCategory` | `barn` (child), `annet` (any) | Service groups in display order; unknown Medal categories land on the fallback |
+| `party` | `{ maxPeople: 3, allowParallel: true, askWhoFirst: true }` | Step 1's rules |
+| `window` | `{ rangeDays: 7, prefetchLimit: 4, prefetchCategory: null }` | Bookable window and page prefetch |
+| `dayparts` | `formiddag` 0–12, `ettermiddag` 12–17, `kveld` 17–24 | Named parts of the day, contiguous from 0 to 24 |
+| `portal` | disabled; cookie `booking_portal` (+ derived `_next`, `__Host-…_vipps_bind`, `_vipps_link`) | Customer portal switches and cookie names |
+| `consent` | `{ termsUrl: null, marketing: null }` | The marketing sentence and its version are the site's own |
+| `storageNamespace` | `medal` | Browser keys are `<ns>:booking:draft`, `<ns>:booking:attempt`, `<ns>:booking:rebook-who` |
+| `ics` | `-//Medal Social//Booking//EN` | Calendar product id and UID domain |
+| `labels` | built-in pack for `locale` | Partial copy overrides (`summary.pickTime`, `daypart.<key>`, …) |
+
+A site moving onto the package keeps its live sessions, drafts and cache
+entries by passing the paths, cookie names and storage namespace it already
+uses.
+
+## The UI (`/react`)
+
+The screens are meda's; the package feeds them. A site needs Tailwind v4 and
+three of meda's stylesheets, and themes them with its own shadcn variables
+(`--primary`, `--card`, …):
+
+```css
+@import '@medalsocial/meda/styles/bridge.css';
+@import '@medalsocial/meda/primitives/styles.css'; /* the sheets and dialogs the screens open */
+@import '@medalsocial/meda/booking/styles.css';
+```
+
+Without the primitives sheet the login sheet's positioning classes are never
+generated, and it opens at the top of the page.
+
+```tsx
+// app/bestill/page.tsx — a Server Component
+import { resolveBookingConfig } from '@medalsocial/booking/core';
+import { BookingWizard } from '@medalsocial/booking/react/wizard';
+import { mergeLabels } from '@medalsocial/booking/react/shared';
+import { startLogin, startVipps } from './actions'; // the app's 'use server' wrappers
+
+const config = resolveBookingConfig({
+  timeZone: 'Europe/Oslo',
+  // Resolved here, so the browser bundle carries no copy it does not show.
+  labels: mergeLabels('nb-NO', { 'who.heading': 'Hvem gjelder timen?' }),
+});
+
+export default async function Page() {
+  const seed = await loadSeed(); // `/next`'s loader
+  return <BookingWizard config={config} seed={seed} actions={{ startLogin, startVipps }} />;
+}
+```
+
+The override ladder, cheapest first, all public API:
+
+1. **CSS variables** — the bridge's shadcn names.
+2. **`labels`** — any key of `BookingLabels`, over the pack in `config.labels`
+   (see [Labels and text nodes](#labels-and-text-nodes)).
+3. **`classNames`** — per screen and slot: `classNames={{ who: { chip: '…' }, time: { chip: '…' } }}`.
+4. **`components`** — card renderers: `components={{ ServiceCard, StylistCard, TimeChip, … }}`.
+5. **`useBooking()`** — the wizard's whole state, fetches and actions, without its markup.
+
+`<BookingProvider config labels classNames components>` shares one set of
+these with every booking piece under it. Server actions stay in the app
+(`PortalActions`): each is a three-line `'use server'` wrapper passed in as a
+prop, answering with its result or with next-safe-action's envelope.
+
+### Labels and text nodes
+
+A label is a `BookingLabel`: a `string` or an array of strings. Both forms are
+serialisable and work for every key. They differ only in the DOM they render as:
+
+- A **string** is ONE text node once its `{holes}` are filled, the way a
+  template literal is.
+- An **array** is one text node per element, each element filled with the same
+  values. For example, `['Steg ', '{step}', ' av ', '{total}']` is four nodes,
+  the DOM of `Steg {step} av {total}` written out in JSX. An element that fills
+  to `''` renders nothing.
+
+A browser lays text out per text node, so a site moving onto these screens
+from its own JSX can match its old pixels by writing each sentence in the shape
+its old markup had. Text-only targets read an array joined: `aria-label`, the
+calendar file, its name, and messages.
+
+The built-in packs are strings, except the three sentences the package itself
+draws in pieces: `wizard.progress`, `wizard.slotsUnavailable.call` and
+`portal.greeting`. `wizard.party.sizeWord.two` / `.three` / `.other` spell the
+party size («to», «tre», «flere») for `{sizeWord}` in the stylist step's
+`stylist.party.parallel.*` and `stylist.party.parallelNote.*`. Left blank, the
+number is filled in instead. An array for a meda screen key needs
+`@medalsocial/meda` 3.4 or later.
+
+## Server (`/next`)
+
+```ts
+// lib/booking/server.ts
+import 'server-only';
+import { createBookingServer } from '@medalsocial/booking/next';
+import { nextDataCacheAdapter } from '@medalsocial/booking/next/cache/next-data';
+import { workersCacheAdapter } from '@medalsocial/booking/next/cache/workers';
+
+export const booking = createBookingServer({
+  config: bookingConfig,
+  // Functions, so the key is read per request (OpenNext fills process.env late).
+  medal: { apiKey: () => process.env.MEDAL_API_KEY, baseUrl: () => process.env.MEDAL_API_ENDPOINT },
+  cache: {
+    edge: workersCacheAdapter({ origin: () => process.env.NEXT_PUBLIC_BASE_URL }),
+    data: nextDataCacheAdapter(),
+    prefix: 'my-site-booking',
+    environment: 'production',
+  },
+});
+
+// app/api/booking/[...path]/route.ts and app/api/portal/[...path]/route.ts
+export const { GET, POST, DELETE } = booking.handler;
+```
+
+- **Pages** call `booking.loadBookingPage({ searchParams })`,
+  `booking.loadManagePage(token)` and `booking.loadPortalPage()`; each answers
+  a tagged result (`redirect`, `unavailable`, `ready`, …) and the page renders it.
+- **Server actions stay in the app.** `booking.portal.actions.*` are plain async
+  functions; wrap each in a `'use server'` export and pass it to the components.
+- **Caches.** `edge` holds the booking seed (per location, a few ms); `data`
+  holds services, stylists, hours and free slots. On Node use
+  `memoryCacheAdapter()` for both. Every adapter keeps one contract
+  (`tests/next/cache/contract.test.ts`).
+- **Stylist photos.** `/api/booking/avatar/<id>` fetches a stylist's photo
+  server-side and serves it from the site with a day of browser cache. It
+  fetches only from `avatarHosts` (exact names or `*.` suffixes; default
+  `DEFAULT_AVATAR_HOSTS`, Medal's photo storage and Google profile pictures),
+  over `https:` on the default port, never from an IP address or internal
+  name and never through a redirect, and it relays only JPEG, PNG, WebP, AVIF
+  and GIF. A photo anywhere else falls back to the stylist's initials.
+- `examples/next-booking` is a runnable site on plain `next start`.
+
+## Development
+
+```bash
+pnpm --filter @medalsocial/booking test          # node + jsdom projects
+pnpm --filter @medalsocial/booking test:coverage # 100% thresholds
+pnpm --filter @medalsocial/booking build
+pnpm --filter @medalsocial/booking verify:paths  # export map + bare-Node core check
+pnpm --filter @medalsocial/booking size:budget   # gzip budgets, esbuild-bundled
+```
+
+`/core` may import nothing from React, Next, `server-only` or meda — Biome's
+`noRestrictedImports` and `tests/core/boundary.test.ts` both enforce it. This
+repository is public: no customer names, copy or data in any file
+(`tests/core/denylist.test.ts`).
+
+## License
+
+Apache-2.0

package/dist/core/age.d.mts

@@ -0,0 +1,34 @@
+import { BookingConfig } from "./config.mjs";
+//#region src/core/age.d.ts
+type AgeConfig = Pick<BookingConfig, 'categories' | 'fallbackCategory' | 'locale' | 'labels'>;
+export interface AgeRange {
+  /** Inclusive; equal to `max` when the age is exact. */
+  min: number;
+  max: number;
+}
+export declare function ageOnDay(birthYear: number, birthMonth: number | null | undefined, dayKey: string): AgeRange | null;
+/** A service's age range, as the wizard carries it (`WizardService`). */
+export interface AgeBounds {
+  ageMinYears?: number;
+  ageMaxYears?: number;
+}
+/**
+ * Whether a service can be suggested for a child of this age. Only a CERTAIN
+ * miss rules it out: a child who is «6–7 år» is not too old for a service up
+ * to 6, because they may still be six on the day. `null` — nobody's age is
+ * known (a guest, a grown-up) — fits everything.
+ */
+export declare function fitsAge(service: AgeBounds, age: AgeRange | null): boolean;
+export interface Age {
+  ageOnDay: typeof ageOnDay;
+  fitsAge: typeof fitsAge;
+  ageLabel(range: AgeRange): string;
+  grownUpEquivalent<S extends AgeBounds & {
+    id: string;
+    name: string;
+    category: string;
+  }>(last: S, candidates: readonly S[], age: AgeRange | null): S | null;
+}
+export declare function createAge(config: AgeConfig): Age;
+//#endregion
+//# sourceMappingURL=age.d.mts.map

package/dist/core/age.mjs

@@ -0,0 +1,95 @@
+import { adultEquivalent } from "./categories.mjs";
+import { fill, resolveLabels } from "./labels.mjs";
+//#region src/core/age.ts
+/**
+* How old a child is ON THE APPOINTMENT DAY — the one age that decides which
+* haircut and which price they get.
+*
+* The profile keeps a birth YEAR and, since SP10, optionally a birth MONTH —
+* never a full date (data minimisation for children). So the answer is a
+* RANGE: with the month it is exact (Medal's own `ageOnDay` counts the
+* birthday as the first of the month, and this agrees with it), without it
+* the child is one of two ages depending on whether the birthday has been yet
+* this year, which the card says honestly as «7–8 år».
+*
+* `dayKey` is `clock.dayKey`'s `2026-08-29` — the SALON's calendar date, not the
+* viewer's, for the reason every date on this site is.
+*
+* Pure and dependency-free, so the wizard (a browser bundle) and the portal (a
+* server render) read the same number.
+*
+* `ageOnDay` and `fitsAge` are config-free; `createAge(config)` adds the two
+* that are not — the label's words, and which adult group a kids' service
+* grows up into (`categories[].adultEquivalent`, which replaced a hard-coded
+* table of Norwegian service names).
+*/
+function ageOnDay(birthYear, birthMonth, dayKey) {
+	const year = Number(dayKey.slice(0, 4));
+	const month = Number(dayKey.slice(5, 7));
+	if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(birthYear)) return null;
+	const yearDiff = year - birthYear;
+	if (yearDiff < 0) return null;
+	if (typeof birthMonth === "number" && Number.isInteger(birthMonth) && birthMonth >= 1 && birthMonth <= 12) {
+		const exact = month < birthMonth ? yearDiff - 1 : yearDiff;
+		return exact < 0 ? null : {
+			min: exact,
+			max: exact
+		};
+	}
+	return {
+		min: Math.max(0, yearDiff - 1),
+		max: yearDiff
+	};
+}
+/** «7 år», or «7–8 år» when only the year is known — in the words of `labels`. */
+function ageLabel(labels, range) {
+	return range.min === range.max ? fill(labels["age.exact"], { min: range.min }) : fill(labels["age.range"], {
+		min: range.min,
+		max: range.max
+	});
+}
+/**
+* Whether a service can be suggested for a child of this age. Only a CERTAIN
+* miss rules it out: a child who is «6–7 år» is not too old for a service up
+* to 6, because they may still be six on the day. `null` — nobody's age is
+* known (a guest, a grown-up) — fits everything.
+*/
+function fitsAge(service, age) {
+	if (age === null) return true;
+	if (service.ageMaxYears !== void 0 && age.min > service.ageMaxYears) return false;
+	if (service.ageMinYears !== void 0 && age.max < service.ageMinYears) return false;
+	return true;
+}
+/**
+* What «Samme som sist» becomes for a child who has outgrown their last cut:
+* the one service in the same category that fits their age now — an
+* age-banded one first (a «Barnehageklipp» child is a «Barneklipp» child at
+* seven) — or — where the
+* category holds none — the grown-up cut its group's `adultEquivalent` points at (by
+* name: «gutt» → the men's group, «jente» → the women's), again only when
+* exactly one fits. Anything less
+* certain is `null`: the parent picks from the menu, which is better than a
+* guess that books the wrong cut at the wrong price.
+*/
+function grownUpEquivalent(config, last, candidates, age) {
+	const fitting = candidates.filter((service) => service.id !== last.id && fitsAge(service, age));
+	const sameCategory = fitting.filter((service) => service.category === last.category);
+	const banded = sameCategory.filter((service) => service.ageMinYears !== void 0 || service.ageMaxYears !== void 0);
+	if (banded.length === 1) return banded[0];
+	if (sameCategory.length === 1) return sameCategory[0];
+	const grownUp = adultEquivalent(config, last, fitting);
+	return grownUp.length === 1 ? grownUp[0] : null;
+}
+function createAge(config) {
+	const labels = resolveLabels(config.locale, config.labels);
+	return {
+		ageOnDay,
+		fitsAge,
+		ageLabel: (range) => ageLabel(labels, range),
+		grownUpEquivalent: (last, candidates, age) => grownUpEquivalent(config, last, candidates, age)
+	};
+}
+//#endregion
+export { ageOnDay, createAge, fitsAge };
+
+//# sourceMappingURL=age.mjs.map

package/dist/core/age.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"age.mjs","names":[],"sources":["../../src/core/age.ts"],"sourcesContent":["/**\n * How old a child is ON THE APPOINTMENT DAY — the one age that decides which\n * haircut and which price they get.\n *\n * The profile keeps a birth YEAR and, since SP10, optionally a birth MONTH —\n * never a full date (data minimisation for children). So the answer is a\n * RANGE: with the month it is exact (Medal's own `ageOnDay` counts the\n * birthday as the first of the month, and this agrees with it), without it\n * the child is one of two ages depending on whether the birthday has been yet\n * this year, which the card says honestly as «7–8 år».\n *\n * `dayKey` is `clock.dayKey`'s `2026-08-29` — the SALON's calendar date, not the\n * viewer's, for the reason every date on this site is.\n *\n * Pure and dependency-free, so the wizard (a browser bundle) and the portal (a\n * server render) read the same number.\n *\n * `ageOnDay` and `fitsAge` are config-free; `createAge(config)` adds the two\n * that are not — the label's words, and which adult group a kids' service\n * grows up into (`categories[].adultEquivalent`, which replaced a hard-coded\n * table of Norwegian service names).\n */\n\nimport { adultEquivalent } from './categories';\nimport type { BookingConfig } from './config';\nimport { type BookingLabels, fill, resolveLabels } from './labels';\n\ntype AgeConfig = Pick<BookingConfig, 'categories' | 'fallbackCategory' | 'locale' | 'labels'>;\n\nexport interface AgeRange {\n  /** Inclusive; equal to `max` when the age is exact. */\n  min: number;\n  max: number;\n}\n\nexport function ageOnDay(\n  birthYear: number,\n  birthMonth: number | null | undefined,\n  dayKey: string\n): AgeRange | null {\n  const year = Number(dayKey.slice(0, 4));\n  const month = Number(dayKey.slice(5, 7));\n  if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(birthYear)) {\n    return null;\n  }\n  const yearDiff = year - birthYear;\n  if (yearDiff < 0) return null;\n  const hasMonth =\n    typeof birthMonth === 'number' &&\n    Number.isInteger(birthMonth) &&\n    birthMonth >= 1 &&\n    birthMonth <= 12;\n  if (hasMonth) {\n    const exact = month < birthMonth ? yearDiff - 1 : yearDiff;\n    return exact < 0 ? null : { min: exact, max: exact };\n  }\n  return { min: Math.max(0, yearDiff - 1), max: yearDiff };\n}\n\n/** «7 år», or «7–8 år» when only the year is known — in the words of `labels`. */\nfunction ageLabel(labels: Readonly<BookingLabels>, range: AgeRange): string {\n  return range.min === range.max\n    ? fill(labels['age.exact'], { min: range.min })\n    : fill(labels['age.range'], { min: range.min, max: range.max });\n}\n\n/** A service's age range, as the wizard carries it (`WizardService`). */\nexport interface AgeBounds {\n  ageMinYears?: number;\n  ageMaxYears?: number;\n}\n\n/**\n * Whether a service can be suggested for a child of this age. Only a CERTAIN\n * miss rules it out: a child who is «6–7 år» is not too old for a service up\n * to 6, because they may still be six on the day. `null` — nobody's age is\n * known (a guest, a grown-up) — fits everything.\n */\nexport function fitsAge(service: AgeBounds, age: AgeRange | null): boolean {\n  if (age === null) return true;\n  if (service.ageMaxYears !== undefined && age.min > service.ageMaxYears) return false;\n  if (service.ageMinYears !== undefined && age.max < service.ageMinYears) return false;\n  return true;\n}\n\n/**\n * What «Samme som sist» becomes for a child who has outgrown their last cut:\n * the one service in the same category that fits their age now — an\n * age-banded one first (a «Barnehageklipp» child is a «Barneklipp» child at\n * seven) — or — where the\n * category holds none — the grown-up cut its group's `adultEquivalent` points at (by\n * name: «gutt» → the men's group, «jente» → the women's), again only when\n * exactly one fits. Anything less\n * certain is `null`: the parent picks from the menu, which is better than a\n * guess that books the wrong cut at the wrong price.\n */\nfunction grownUpEquivalent<S extends AgeBounds & { id: string; name: string; category: string }>(\n  config: AgeConfig,\n  last: S,\n  candidates: readonly S[],\n  age: AgeRange | null\n): S | null {\n  const fitting = candidates.filter((service) => service.id !== last.id && fitsAge(service, age));\n  const sameCategory = fitting.filter((service) => service.category === last.category);\n  // A service the salon banded by age is the likelier «next size up» than one\n  // it did not — «Barneklipp 7–12» over «Hull i ørene» — so those are asked first.\n  const banded = sameCategory.filter(\n    (service) => service.ageMinYears !== undefined || service.ageMaxYears !== undefined\n  );\n  if (banded.length === 1) return banded[0];\n  if (sameCategory.length === 1) return sameCategory[0];\n  const grownUp = adultEquivalent(config, last, fitting);\n  return grownUp.length === 1 ? grownUp[0] : null;\n}\n\nexport interface Age {\n  ageOnDay: typeof ageOnDay;\n  fitsAge: typeof fitsAge;\n  ageLabel(range: AgeRange): string;\n  grownUpEquivalent<S extends AgeBounds & { id: string; name: string; category: string }>(\n    last: S,\n    candidates: readonly S[],\n    age: AgeRange | null\n  ): S | null;\n}\n\nexport function createAge(config: AgeConfig): Age {\n  const labels = resolveLabels(config.locale, config.labels);\n  return {\n    ageOnDay,\n    fitsAge,\n    ageLabel: (range) => ageLabel(labels, range),\n    grownUpEquivalent: (last, candidates, age) => grownUpEquivalent(config, last, candidates, age),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,SACd,WACA,YACA,QACiB;CACjB,MAAM,OAAO,OAAO,OAAO,MAAM,GAAG,CAAC,CAAC;CACtC,MAAM,QAAQ,OAAO,OAAO,MAAM,GAAG,CAAC,CAAC;CACvC,IAAI,CAAC,OAAO,UAAU,IAAI,KAAK,CAAC,OAAO,UAAU,KAAK,KAAK,CAAC,OAAO,UAAU,SAAS,GACpF,OAAO;CAET,MAAM,WAAW,OAAO;CACxB,IAAI,WAAW,GAAG,OAAO;CAMzB,IAJE,OAAO,eAAe,YACtB,OAAO,UAAU,UAAU,KAC3B,cAAc,KACd,cAAc,IACF;EACZ,MAAM,QAAQ,QAAQ,aAAa,WAAW,IAAI;EAClD,OAAO,QAAQ,IAAI,OAAO;GAAE,KAAK;GAAO,KAAK;EAAM;CACrD;CACA,OAAO;EAAE,KAAK,KAAK,IAAI,GAAG,WAAW,CAAC;EAAG,KAAK;CAAS;AACzD;;AAGA,SAAS,SAAS,QAAiC,OAAyB;CAC1E,OAAO,MAAM,QAAQ,MAAM,MACvB,KAAK,OAAO,cAAc,EAAE,KAAK,MAAM,IAAI,CAAC,IAC5C,KAAK,OAAO,cAAc;EAAE,KAAK,MAAM;EAAK,KAAK,MAAM;CAAI,CAAC;AAClE;;;;;;;AAcA,SAAgB,QAAQ,SAAoB,KAA+B;CACzE,IAAI,QAAQ,MAAM,OAAO;CACzB,IAAI,QAAQ,gBAAgB,KAAA,KAAa,IAAI,MAAM,QAAQ,aAAa,OAAO;CAC/E,IAAI,QAAQ,gBAAgB,KAAA,KAAa,IAAI,MAAM,QAAQ,aAAa,OAAO;CAC/E,OAAO;AACT;;;;;;;;;;;;AAaA,SAAS,kBACP,QACA,MACA,YACA,KACU;CACV,MAAM,UAAU,WAAW,QAAQ,YAAY,QAAQ,OAAO,KAAK,MAAM,QAAQ,SAAS,GAAG,CAAC;CAC9F,MAAM,eAAe,QAAQ,QAAQ,YAAY,QAAQ,aAAa,KAAK,QAAQ;CAGnF,MAAM,SAAS,aAAa,QACzB,YAAY,QAAQ,gBAAgB,KAAA,KAAa,QAAQ,gBAAgB,KAAA,CAC5E;CACA,IAAI,OAAO,WAAW,GAAG,OAAO,OAAO;CACvC,IAAI,aAAa,WAAW,GAAG,OAAO,aAAa;CACnD,MAAM,UAAU,gBAAgB,QAAQ,MAAM,OAAO;CACrD,OAAO,QAAQ,WAAW,IAAI,QAAQ,KAAK;AAC7C;AAaA,SAAgB,UAAU,QAAwB;CAChD,MAAM,SAAS,cAAc,OAAO,QAAQ,OAAO,MAAM;CACzD,OAAO;EACL;EACA;EACA,WAAW,UAAU,SAAS,QAAQ,KAAK;EAC3C,oBAAoB,MAAM,YAAY,QAAQ,kBAAkB,QAAQ,MAAM,YAAY,GAAG;CAC/F;AACF"}