@happyvertical/smrt-human-resources 0.0.0-stage → 0.53.5

package/dist/svelte/types.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Serializable view types and pure helpers for the HR components.
+ *
+ * Components take plain view objects (not model instances) so hosts can pass
+ * data across the server/client boundary. HR holds no identity data, so every
+ * name on a view comes from the host. Dates are `YYYY-MM-DD` calendar dates:
+ * all arithmetic here is UTC, never local time. Explicit interfaces (not
+ * inline intersections) keep Svelte 5 prop type evaluation cheap.
+ */
+import type { Employment } from '../employment/models.js';
+import type { ProfileQualification } from '../qualifications/service.js';
+import type { EmploymentStatus, HeldQualificationStatus, IsoDate, QualificationKind } from '../types.js';
+/** Status of a held qualification on one date (mirrors the service's type). */
+export type QualificationStatusOn = HeldQualificationStatus | 'not-yet-issued';
+/** One row of `EmployeeList`. */
+export interface EmployeeView {
+    /** The `Employment` id. */
+    id: string;
+    /** The person's name, supplied by the host (for example from smrt-profiles). */
+    displayName: string;
+    employeeNumber: string;
+    position: string | null;
+    workerType: string;
+    status: EmploymentStatus;
+    /** First day of the current (or latest) term; null when the host has none. */
+    startedOn: IsoDate | null;
+    /**
+     * The last day employed when an end has been recorded (the latest term's
+     * `endedOn`); null or omitted otherwise. `EmployeeList` shows it next to the
+     * status and never compares it with today.
+     */
+    endsOn?: IsoDate | null;
+}
+/** The employment fields `toEmployeeView` reads; an `Employment` satisfies it. */
+export interface EmploymentLike {
+    id?: string | null;
+    employeeNumber: string;
+    position: string | null;
+    workerType: string;
+    status: EmploymentStatus;
+    userId?: string | null;
+}
+/** Existing values passed to `EmployeeForm` when editing. */
+export interface EmployeeFormInitial {
+    employeeNumber: string;
+    workerType: string;
+    position: string | null;
+    /** The linked login (`smrt-users:User` id), if any. */
+    userId: string | null;
+}
+/**
+ * What `EmployeeForm` hands to `onsubmit`. Values are trimmed; a blank
+ * position or login is null. The host maps them onto `EmploymentService`:
+ * a new hire onto `hire` (with the profile it chose), an edit onto
+ * `changePosition` / `changeWorkerType` / `linkLogin` / `unlinkLogin` for each
+ * value that differs from the stored employment, each dated `effectiveOn`.
+ * A login link or unlink takes effect at once whatever the date, so a
+ * future-dated edit that also clears the login unlinks it immediately.
+ */
+export interface EmployeeFormValues {
+    employeeNumber: string;
+    workerType: string;
+    position: string | null;
+    userId: string | null;
+    /** First day employed. Set for a new hire, null for an edit. */
+    startedOn: IsoDate | null;
+    /** The day an edit's changes take effect. Set for an edit, null for a new hire. */
+    effectiveOn: IsoDate | null;
+}
+/** A login the host offers in `EmployeeForm`'s login field. */
+export interface EmployeeLoginOption {
+    /** The `smrt-users:User` id. */
+    value: string;
+    /** What the person sees, for example an email address. */
+    label: string;
+}
+/** One row of `PersonQualifications`. */
+export interface PersonQualificationView {
+    /** The `HeldQualification` id. */
+    id: string;
+    name: string;
+    kind: QualificationKind;
+    issuingBody: string;
+    certificateNumber: string;
+    issuedOn: IsoDate;
+    /** Last day valid, inclusive; null never expires. */
+    expiresOn: IsoDate | null;
+    /** Status as of the host's "today". */
+    status: QualificationStatusOn;
+    /** Whole days from today to `expiresOn` (negative once past); null never expires. */
+    daysUntilExpiry: number | null;
+}
+/** The held-qualification fields the adapters read. */
+export interface HeldQualificationLike {
+    id?: string | null;
+    issuedOn: IsoDate;
+    expiresOn: IsoDate | null;
+    certificateNumber: string;
+}
+/** The definition fields the adapters read. */
+export interface QualificationLike {
+    name: string;
+    kind: QualificationKind;
+    issuingBody: string;
+}
+/** A `QualificationService.listForProfile` row, structurally. */
+export interface ProfileQualificationLike {
+    held: HeldQualificationLike;
+    qualification: QualificationLike;
+    status: QualificationStatusOn;
+}
+/** Resolves to `Row`, and fails to compile unless `Row` is assignable to `Like`. */
+type Satisfies<Like, Row extends Like> = Row;
+/**
+ * Compile-time proof that what the services return fits the structural
+ * inputs of the adapters below: an `Employment` is an {@link EmploymentLike}
+ * and a `listForProfile` row is a {@link ProfileQualificationLike}. Typecheck
+ * fails here if a model and its view input drift apart.
+ */
+export type HrViewInputs = [
+    Satisfies<EmploymentLike, Employment>,
+    Satisfies<ProfileQualificationLike, ProfileQualification>
+];
+/** One row of `ExpiringQualificationsList`. */
+export interface ExpiringQualificationView {
+    /** The `HeldQualification` id. */
+    id: string;
+    /** The holder's name, supplied by the host. */
+    displayName: string;
+    qualificationName: string;
+    expiresOn: IsoDate;
+    daysUntilExpiry: number;
+}
+/** How a qualification is shown: its status, with "expiring soon" split out. */
+export type QualificationExpiryState = 'valid' | 'expiring-soon' | 'expired' | 'suspended' | 'revoked' | 'not-yet-issued';
+/** Default "expiring soon" window, in days. */
+export declare const DEFAULT_EXPIRING_SOON_DAYS = 30;
+/** Whether `value` is a real calendar date written `YYYY-MM-DD`. */
+export declare function isCalendarDate(value: unknown): value is IsoDate;
+/**
+ * Whole calendar days from `today` to `date` (negative when `date` is past).
+ * Both are `YYYY-MM-DD`; the arithmetic is UTC, so no timezone or daylight
+ * saving shift can move the answer.
+ *
+ * @throws RangeError when either value is not a real calendar date
+ */
+export declare function daysUntil(today: IsoDate, date: IsoDate): number;
+/** Whether a worker type is lowercase kebab-case, as the service requires. */
+export declare function isWorkerType(value: string): boolean;
+/** Message key for an employment status label. */
+export declare function employmentStatusLabelKey(status: EmploymentStatus): 'human_resources.employee_list.status_active' | 'human_resources.employee_list.status_on_leave' | 'human_resources.employee_list.status_ended';
+/** Map an employment status onto `StatusBadge` default color-scheme keys. */
+export declare function employmentStatusBadgeKey(status: EmploymentStatus): string;
+/**
+ * How to show a qualification: its status, with a valid one whose last day is
+ * within `expiringSoonDays` (inclusive, counting today) reported as
+ * `expiring-soon`. A `valid` row whose last day has passed shows as expired.
+ */
+export declare function qualificationExpiryState(view: Pick<PersonQualificationView, 'status' | 'daysUntilExpiry'>, expiringSoonDays?: number): QualificationExpiryState;
+/** Message key for a qualification expiry state label. */
+export declare function qualificationStateLabelKey(state: QualificationExpiryState): 'human_resources.person_qualifications.state_valid' | 'human_resources.person_qualifications.state_expiring_soon' | 'human_resources.person_qualifications.state_expired' | 'human_resources.person_qualifications.state_suspended' | 'human_resources.person_qualifications.state_revoked' | 'human_resources.person_qualifications.state_not_yet_issued';
+/** Map a qualification expiry state onto `StatusBadge` default color-scheme keys. */
+export declare function qualificationStateBadgeKey(state: QualificationExpiryState): string;
+/** Message key for a qualification kind label. */
+export declare function qualificationKindLabelKey(kind: QualificationKind): 'human_resources.person_qualifications.kind_ticket' | 'human_resources.person_qualifications.kind_certification' | 'human_resources.person_qualifications.kind_authorization' | 'human_resources.person_qualifications.kind_training' | 'human_resources.person_qualifications.kind_restriction';
+/**
+ * Adapt an employment to an `EmployeeList` row. The host supplies the name
+ * and the start date (from `EmploymentService.terms`), and may pass the
+ * latest term's `endedOn` as `endsOn` so the list shows the last day employed
+ * beside an `ended` status during a notice period.
+ */
+export declare function toEmployeeView(employment: EmploymentLike, displayName: string, startedOn: IsoDate | null, endsOn?: IsoDate | null): EmployeeView;
+/** Adapt an employment to `EmployeeForm`'s `employee` prop. */
+export declare function toEmployeeFormInitial(employment: EmploymentLike): EmployeeFormInitial;
+/**
+ * Adapt a `QualificationService.listForProfile(profileId, today)` row. Pass
+ * the same `today` given to the service, so the status and the day count agree.
+ */
+export declare function toPersonQualificationView(row: ProfileQualificationLike, today: IsoDate): PersonQualificationView;
+/**
+ * Adapt a `QualificationService.expiringWithin(days, today)` row. The host
+ * supplies the holder's name and the qualification's name.
+ *
+ * @throws RangeError when the held qualification never expires
+ */
+export declare function toExpiringQualificationView(held: HeldQualificationLike, displayName: string, qualificationName: string, today: IsoDate): ExpiringQualificationView;
+/** A copy sorted by soonest expiry, then holder, then qualification name. */
+export declare function sortBySoonestExpiry(items: readonly ExpiringQualificationView[]): ExpiringQualificationView[];
+/**
+ * Message key and day count describing how far away an expiry is. `days` is
+ * always zero or more, for the `{days}` placeholder.
+ */
+export declare function expiryDistance(daysUntilExpiry: number): {
+    key: 'human_resources.expiry.today' | 'human_resources.expiry.in_one_day' | 'human_resources.expiry.in_days' | 'human_resources.expiry.one_day_ago' | 'human_resources.expiry.days_ago';
+    days: number;
+};
+/** A field `validateEmployeeForm` can reject. */
+export type EmployeeFormField = 'employeeNumber' | 'workerType' | 'startedOn' | 'effectiveOn';
+/** Result of {@link validateEmployeeForm}. */
+export type EmployeeFormValidation = {
+    ok: true;
+    values: EmployeeFormValues;
+} | {
+    ok: false;
+    invalid: EmployeeFormField[];
+};
+/** The raw text `EmployeeForm` collects, before trimming and checks. */
+export interface EmployeeFormDraft {
+    employeeNumber: string;
+    workerType: string;
+    position: string;
+    userId: string;
+    startedOn: string;
+    effectiveOn: string;
+}
+/**
+ * Normalize and check an `EmployeeForm` draft against the same field rules
+ * `EmploymentService` enforces: employee number required, worker type
+ * lowercase kebab-case, a real calendar start date for a new hire and a real
+ * calendar effective date for an edit. The values are not a service input by
+ * themselves; see {@link EmployeeFormValues} for how a host maps them.
+ */
+export declare function validateEmployeeForm(draft: Readonly<Partial<EmployeeFormDraft>>, isNew: boolean): EmployeeFormValidation;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/svelte/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/svelte/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,OAAO,EACP,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,GAAG,gBAAgB,CAAC;AAE/E,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gEAAgE;IAChE,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,mFAAmF;IACnF,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yCAAyC;AACzC,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,qFAAqF;IACrF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,aAAa,EAAE,iBAAiB,CAAC;IACjC,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED,oFAAoF;AACpF,KAAK,SAAS,CAAC,IAAI,EAAE,GAAG,SAAS,IAAI,IAAI,GAAG,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,CAAC,cAAc,EAAE,UAAU,CAAC;IACrC,SAAS,CAAC,wBAAwB,EAAE,oBAAoB,CAAC;CAC1D,CAAC;AAEF,+CAA+C;AAC/C,MAAM,WAAW,yBAAyB;IACxC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAChC,OAAO,GACP,eAAe,GACf,SAAS,GACT,WAAW,GACX,SAAS,GACT,gBAAgB,CAAC;AAErB,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAsB7C,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAQ/D;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,kDAAkD;AAClD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,gBAAgB,GAEtB,6CAA6C,GAC7C,+CAA+C,GAC/C,4CAA4C,CAS/C;AAED,6EAA6E;AAC7E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CASzE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,CAAC,uBAAuB,EAAE,QAAQ,GAAG,iBAAiB,CAAC,EACjE,gBAAgB,GAAE,MAAmC,GACpD,wBAAwB,CAK1B;AAED,0DAA0D;AAC1D,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAE7B,mDAAmD,GACnD,2DAA2D,GAC3D,qDAAqD,GACrD,uDAAuD,GACvD,qDAAqD,GACrD,4DAA4D,CAe/D;AAED,qFAAqF;AACrF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAC9B,MAAM,CAcR;AAED,kDAAkD;AAClD,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,iBAAiB,GAErB,mDAAmD,GACnD,0DAA0D,GAC1D,0DAA0D,GAC1D,qDAAqD,GACrD,wDAAwD,CAa3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,cAAc,EAC1B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,GAAG,IAAI,EACzB,MAAM,GAAE,OAAO,GAAG,IAAW,GAC5B,YAAY,CAWd;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,cAAc,GACzB,mBAAmB,CAOrB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,wBAAwB,EAC7B,KAAK,EAAE,OAAO,GACb,uBAAuB,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,qBAAqB,EAC3B,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,OAAO,GACb,yBAAyB,CAU3B;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,yBAAyB,EAAE,GAC1C,yBAAyB,EAAE,CAQ7B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG;IACvD,GAAG,EACC,8BAA8B,GAC9B,mCAAmC,GACnC,gCAAgC,GAChC,oCAAoC,GACpC,iCAAiC,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd,CAWA;AAED,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,aAAa,CAAC;AAElB,8CAA8C;AAC9C,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAAC;AAMhD,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAC3C,KAAK,EAAE,OAAO,GACb,sBAAsB,CAsBxB"}

package/dist/svelte/types.js

@@ -0,0 +1,257 @@
+/**
+ * Serializable view types and pure helpers for the HR components.
+ *
+ * Components take plain view objects (not model instances) so hosts can pass
+ * data across the server/client boundary. HR holds no identity data, so every
+ * name on a view comes from the host. Dates are `YYYY-MM-DD` calendar dates:
+ * all arithmetic here is UTC, never local time. Explicit interfaces (not
+ * inline intersections) keep Svelte 5 prop type evaluation cheap.
+ */
+/** Default "expiring soon" window, in days. */
+export const DEFAULT_EXPIRING_SOON_DAYS = 30;
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DAY_MS = 86_400_000;
+const WORKER_TYPE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** UTC midnight of a `YYYY-MM-DD` date in milliseconds, or null when it is not a real date. */
+function utcDay(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = ISO_DATE.exec(value);
+    if (!match)
+        return null;
+    const [year, month, day] = match.slice(1).map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCFullYear() !== year ||
+        date.getUTCMonth() !== month - 1 ||
+        date.getUTCDate() !== day)
+        return null;
+    return date.getTime();
+}
+/** Whether `value` is a real calendar date written `YYYY-MM-DD`. */
+export function isCalendarDate(value) {
+    return utcDay(value) !== null;
+}
+/**
+ * Whole calendar days from `today` to `date` (negative when `date` is past).
+ * Both are `YYYY-MM-DD`; the arithmetic is UTC, so no timezone or daylight
+ * saving shift can move the answer.
+ *
+ * @throws RangeError when either value is not a real calendar date
+ */
+export function daysUntil(today, date) {
+    const from = utcDay(today);
+    const to = utcDay(date);
+    if (from === null || to === null)
+        throw new RangeError(`daysUntil needs YYYY-MM-DD calendar dates, got '${String(today)}' and '${String(date)}'.`);
+    return Math.round((to - from) / DAY_MS);
+}
+/** Whether a worker type is lowercase kebab-case, as the service requires. */
+export function isWorkerType(value) {
+    return WORKER_TYPE.test(value);
+}
+/** Message key for an employment status label. */
+export function employmentStatusLabelKey(status) {
+    switch (status) {
+        case 'on-leave':
+            return 'human_resources.employee_list.status_on_leave';
+        case 'ended':
+            return 'human_resources.employee_list.status_ended';
+        default:
+            return 'human_resources.employee_list.status_active';
+    }
+}
+/** Map an employment status onto `StatusBadge` default color-scheme keys. */
+export function employmentStatusBadgeKey(status) {
+    switch (status) {
+        case 'on-leave':
+            return 'pending';
+        case 'ended':
+            return 'inactive';
+        default:
+            return 'active';
+    }
+}
+/**
+ * How to show a qualification: its status, with a valid one whose last day is
+ * within `expiringSoonDays` (inclusive, counting today) reported as
+ * `expiring-soon`. A `valid` row whose last day has passed shows as expired.
+ */
+export function qualificationExpiryState(view, expiringSoonDays = DEFAULT_EXPIRING_SOON_DAYS) {
+    if (view.status !== 'valid')
+        return view.status;
+    if (view.daysUntilExpiry === null)
+        return 'valid';
+    if (view.daysUntilExpiry < 0)
+        return 'expired';
+    return view.daysUntilExpiry <= expiringSoonDays ? 'expiring-soon' : 'valid';
+}
+/** Message key for a qualification expiry state label. */
+export function qualificationStateLabelKey(state) {
+    switch (state) {
+        case 'expiring-soon':
+            return 'human_resources.person_qualifications.state_expiring_soon';
+        case 'expired':
+            return 'human_resources.person_qualifications.state_expired';
+        case 'suspended':
+            return 'human_resources.person_qualifications.state_suspended';
+        case 'revoked':
+            return 'human_resources.person_qualifications.state_revoked';
+        case 'not-yet-issued':
+            return 'human_resources.person_qualifications.state_not_yet_issued';
+        default:
+            return 'human_resources.person_qualifications.state_valid';
+    }
+}
+/** Map a qualification expiry state onto `StatusBadge` default color-scheme keys. */
+export function qualificationStateBadgeKey(state) {
+    switch (state) {
+        case 'valid':
+            return 'success';
+        case 'expiring-soon':
+            return 'warning';
+        case 'expired':
+        case 'revoked':
+            return 'error';
+        case 'suspended':
+            return 'pending';
+        default:
+            return 'inactive';
+    }
+}
+/** Message key for a qualification kind label. */
+export function qualificationKindLabelKey(kind) {
+    switch (kind) {
+        case 'ticket':
+            return 'human_resources.person_qualifications.kind_ticket';
+        case 'authorization':
+            return 'human_resources.person_qualifications.kind_authorization';
+        case 'training':
+            return 'human_resources.person_qualifications.kind_training';
+        case 'restriction':
+            return 'human_resources.person_qualifications.kind_restriction';
+        default:
+            return 'human_resources.person_qualifications.kind_certification';
+    }
+}
+/**
+ * Adapt an employment to an `EmployeeList` row. The host supplies the name
+ * and the start date (from `EmploymentService.terms`), and may pass the
+ * latest term's `endedOn` as `endsOn` so the list shows the last day employed
+ * beside an `ended` status during a notice period.
+ */
+export function toEmployeeView(employment, displayName, startedOn, endsOn = null) {
+    return {
+        id: String(employment.id ?? ''),
+        displayName,
+        employeeNumber: employment.employeeNumber,
+        position: employment.position,
+        workerType: employment.workerType,
+        status: employment.status,
+        startedOn,
+        endsOn,
+    };
+}
+/** Adapt an employment to `EmployeeForm`'s `employee` prop. */
+export function toEmployeeFormInitial(employment) {
+    return {
+        employeeNumber: employment.employeeNumber,
+        workerType: employment.workerType,
+        position: employment.position,
+        userId: employment.userId ?? null,
+    };
+}
+/**
+ * Adapt a `QualificationService.listForProfile(profileId, today)` row. Pass
+ * the same `today` given to the service, so the status and the day count agree.
+ */
+export function toPersonQualificationView(row, today) {
+    return {
+        id: String(row.held.id ?? ''),
+        name: row.qualification.name,
+        kind: row.qualification.kind,
+        issuingBody: row.qualification.issuingBody,
+        certificateNumber: row.held.certificateNumber,
+        issuedOn: row.held.issuedOn,
+        expiresOn: row.held.expiresOn,
+        status: row.status,
+        daysUntilExpiry: row.held.expiresOn === null ? null : daysUntil(today, row.held.expiresOn),
+    };
+}
+/**
+ * Adapt a `QualificationService.expiringWithin(days, today)` row. The host
+ * supplies the holder's name and the qualification's name.
+ *
+ * @throws RangeError when the held qualification never expires
+ */
+export function toExpiringQualificationView(held, displayName, qualificationName, today) {
+    if (held.expiresOn === null)
+        throw new RangeError('A qualification that never expires is not expiring.');
+    return {
+        id: String(held.id ?? ''),
+        displayName,
+        qualificationName,
+        expiresOn: held.expiresOn,
+        daysUntilExpiry: daysUntil(today, held.expiresOn),
+    };
+}
+/** A copy sorted by soonest expiry, then holder, then qualification name. */
+export function sortBySoonestExpiry(items) {
+    return [...items].sort((a, b) => a.daysUntilExpiry - b.daysUntilExpiry ||
+        a.expiresOn.localeCompare(b.expiresOn) ||
+        a.displayName.localeCompare(b.displayName) ||
+        a.qualificationName.localeCompare(b.qualificationName));
+}
+/**
+ * Message key and day count describing how far away an expiry is. `days` is
+ * always zero or more, for the `{days}` placeholder.
+ */
+export function expiryDistance(daysUntilExpiry) {
+    const days = Math.abs(daysUntilExpiry);
+    if (daysUntilExpiry === 0)
+        return { key: 'human_resources.expiry.today', days };
+    if (daysUntilExpiry === 1)
+        return { key: 'human_resources.expiry.in_one_day', days };
+    if (daysUntilExpiry > 1)
+        return { key: 'human_resources.expiry.in_days', days };
+    if (daysUntilExpiry === -1)
+        return { key: 'human_resources.expiry.one_day_ago', days };
+    return { key: 'human_resources.expiry.days_ago', days };
+}
+function textOf(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * Normalize and check an `EmployeeForm` draft against the same field rules
+ * `EmploymentService` enforces: employee number required, worker type
+ * lowercase kebab-case, a real calendar start date for a new hire and a real
+ * calendar effective date for an edit. The values are not a service input by
+ * themselves; see {@link EmployeeFormValues} for how a host maps them.
+ */
+export function validateEmployeeForm(draft, isNew) {
+    const employeeNumber = textOf(draft.employeeNumber);
+    const workerType = textOf(draft.workerType);
+    const startedOn = textOf(draft.startedOn);
+    const effectiveOn = textOf(draft.effectiveOn);
+    const invalid = [];
+    if (!employeeNumber)
+        invalid.push('employeeNumber');
+    if (!isWorkerType(workerType))
+        invalid.push('workerType');
+    if (isNew && !isCalendarDate(startedOn))
+        invalid.push('startedOn');
+    if (!isNew && !isCalendarDate(effectiveOn))
+        invalid.push('effectiveOn');
+    if (invalid.length > 0)
+        return { ok: false, invalid };
+    return {
+        ok: true,
+        values: {
+            employeeNumber,
+            workerType,
+            position: textOf(draft.position) || null,
+            userId: textOf(draft.userId) || null,
+            startedOn: isNew ? startedOn : null,
+            effectiveOn: isNew ? null : effectiveOn,
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared vocabulary, actor, event and error types for the HR package.
+ *
+ * @packageDocumentation
+ */
+import type { Employment } from './employment/models.js';
+import type { HeldQualification } from './qualifications/models.js';
+/**
+ * Server-side, trusted scope. The application authorizes the acting person
+ * before constructing a service; `profileId` is recorded as the actor on every
+ * dated change.
+ */
+export interface HrActor {
+    /** The employing tenant. */
+    tenantId: string;
+    /** The profile of the person performing the action. */
+    profileId: string;
+}
+/** A calendar date written `YYYY-MM-DD`; never an instant. */
+export type IsoDate = string;
+/**
+ * Stored employment status. `ended` means an end has been recorded, not that
+ * the person is no longer employed today: the last day may still be ahead (a
+ * notice period). "Employed on a date" is computed from terms; use
+ * `EmploymentService.check`, `employedOn`, `asOf` or `findByUser(userId, on)`.
+ */
+export type EmploymentStatus = 'active' | 'on-leave' | 'ended';
+/**
+ * Allowed changes of the stored status; `ended → active` is a rehire. Leave
+ * recorded inside the final term of an ended employment leaves the status
+ * `ended`.
+ */
+export declare const EMPLOYMENT_STATUS_TRANSITIONS: Record<EmploymentStatus, readonly EmploymentStatus[]>;
+/** Worker types shipped as suggestions; any lowercase kebab-case value works. */
+export declare const SUGGESTED_WORKER_TYPES: readonly ["employee", "apprentice", "contractor"];
+/** An open vocabulary: the suggestions, or an application's own value. */
+export type WorkerType = (typeof SUGGESTED_WORKER_TYPES)[number] | (string & {});
+/** Kinds of dated change kept in the employment history. */
+export type EmploymentChangeKind = 'hired' | 'ended' | 'rehired' | 'position-changed' | 'worker-type-changed' | 'leave-started' | 'leave-ended' | 'login-linked' | 'login-unlinked';
+/**
+ * What a qualification is. A `restriction` (for example "youth worker") limits
+ * what its holder may do instead of permitting something.
+ */
+export type QualificationKind = 'ticket' | 'certification' | 'authorization' | 'training' | 'restriction';
+/**
+ * Who a held qualification belongs to: the `person` (it survives a change of
+ * employment) or the `employment` (it ends with it).
+ */
+export type QualificationScope = 'person' | 'employment';
+/** Stored held-qualification status. Expiry on a date is computed. */
+export type HeldQualificationStatus = 'valid' | 'expired' | 'suspended' | 'revoked';
+/** Kinds of dated change kept in a held qualification's history. */
+export type HeldQualificationChangeKind = 'granted' | 'renewed' | 'suspended' | 'reinstated' | 'revoked' | 'expired';
+/** Result of asking whether a profile is employed on a date. */
+export type EmploymentCheck = {
+    ok: true;
+    employmentId: string;
+    onLeave: boolean;
+} | {
+    ok: false;
+    reason: 'not-employed' | 'not-started' | 'ended';
+};
+/** Result of asking whether a profile holds a qualification on a date. */
+export type QualificationCheck = {
+    ok: true;
+    heldQualificationId: string;
+    expiresOn: IsoDate | null;
+} | {
+    ok: false;
+    reason: 'not-held' | 'not-yet-issued' | 'expired' | 'suspended' | 'revoked';
+};
+/** Lifecycle events for an employment. */
+export type EmploymentEventType = 'employment.hired' | 'employment.ended' | 'employment.rehired' | 'employment.position-changed' | 'employment.worker-type-changed' | 'employment.leave-started' | 'employment.leave-ended';
+/** Lifecycle events for a held qualification. */
+export type HeldQualificationEventType = 'held-qualification.granted' | 'held-qualification.renewed' | 'held-qualification.suspended' | 'held-qualification.reinstated' | 'held-qualification.revoked' | 'held-qualification.expired';
+/** Payload delivered to an {@link HrEventHandler}. */
+export type HrEvent = {
+    type: EmploymentEventType;
+    employment: Employment;
+    /** The calendar date the change takes effect. */
+    effectiveOn: IsoDate;
+    at: Date;
+    byProfileId: string;
+} | {
+    type: HeldQualificationEventType;
+    heldQualification: HeldQualification;
+    effectiveOn: IsoDate;
+    at: Date;
+    byProfileId: string;
+};
+/**
+ * Event hook an application provides to react to HR changes (reminders are the
+ * application's business). Called after the service's own transaction
+ * commits. Delivery is best-effort: a throwing handler is logged and
+ * swallowed, so it never rolls back a persisted change.
+ *
+ * "After commit" holds because a service only mutates through the root
+ * database handle. A service constructed with a handle that is already inside
+ * a transaction refuses every mutation (`HR_TRANSACTION_UNSUPPORTED`), so an
+ * event is never delivered for rows an outer rollback could still remove.
+ */
+export type HrEventHandler = (event: HrEvent) => void | Promise<void>;
+/** Options shared by the HR services. */
+export interface HrServiceOptions {
+    /**
+     * Optional lifecycle event hook, called after each mutation commits. The
+     * service must be constructed with the root database handle; see
+     * {@link HrEventHandler}.
+     */
+    onEvent?: HrEventHandler;
+}
+/** Stable error codes raised by this package. */
+export type HrErrorCode = 'HR_INVALID' | 'HR_NOT_FOUND' | 'HR_ACTOR_INVALID' | 'HR_TENANT_MISMATCH' | 'HR_WRITE_FORBIDDEN' | 'HR_HISTORY_IMMUTABLE' | 'HR_STATUS_TRANSITION' | 'HR_EMPLOYEE_NUMBER_TAKEN' | 'HR_ALREADY_EMPLOYED' | 'HR_TERM_OVERLAP' | 'HR_QUALIFICATION_KEY_TAKEN' | 'HR_ALREADY_HELD' | 'HR_QUALIFICATION_SCOPE' | 'HR_TRANSACTION_UNSUPPORTED';
+/** Base error for this package. `code` is stable and safe to branch on. */
+export declare class HrError extends Error {
+    readonly code: HrErrorCode;
+    constructor(code: HrErrorCode, message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,23 @@
+//#region src/types.ts
+var EMPLOYMENT_STATUS_TRANSITIONS = {
+	active: ["on-leave", "ended"],
+	"on-leave": ["active", "ended"],
+	ended: ["active"]
+};
+var SUGGESTED_WORKER_TYPES = [
+	"employee",
+	"apprentice",
+	"contractor"
+];
+var HrError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "HrError";
+		this.code = code;
+	}
+};
+//#endregion
+export { EMPLOYMENT_STATUS_TRANSITIONS, HrError, SUGGESTED_WORKER_TYPES };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/**\n * Shared vocabulary, actor, event and error types for the HR package.\n *\n * @packageDocumentation\n */\n\nimport type { Employment } from './employment/models.js';\nimport type { HeldQualification } from './qualifications/models.js';\n\n/**\n * Server-side, trusted scope. The application authorizes the acting person\n * before constructing a service; `profileId` is recorded as the actor on every\n * dated change.\n */\nexport interface HrActor {\n  /** The employing tenant. */\n  tenantId: string;\n  /** The profile of the person performing the action. */\n  profileId: string;\n}\n\n/** A calendar date written `YYYY-MM-DD`; never an instant. */\nexport type IsoDate = string;\n\n/**\n * Stored employment status. `ended` means an end has been recorded, not that\n * the person is no longer employed today: the last day may still be ahead (a\n * notice period). \"Employed on a date\" is computed from terms; use\n * `EmploymentService.check`, `employedOn`, `asOf` or `findByUser(userId, on)`.\n */\nexport type EmploymentStatus = 'active' | 'on-leave' | 'ended';\n\n/**\n * Allowed changes of the stored status; `ended → active` is a rehire. Leave\n * recorded inside the final term of an ended employment leaves the status\n * `ended`.\n */\nexport const EMPLOYMENT_STATUS_TRANSITIONS: Record<\n  EmploymentStatus,\n  readonly EmploymentStatus[]\n> = {\n  active: ['on-leave', 'ended'],\n  'on-leave': ['active', 'ended'],\n  ended: ['active'],\n};\n\n/** Worker types shipped as suggestions; any lowercase kebab-case value works. */\nexport const SUGGESTED_WORKER_TYPES = [\n  'employee',\n  'apprentice',\n  'contractor',\n] as const;\n/** An open vocabulary: the suggestions, or an application's own value. */\nexport type WorkerType =\n  | (typeof SUGGESTED_WORKER_TYPES)[number]\n  | (string & {});\n\n/** Kinds of dated change kept in the employment history. */\nexport type EmploymentChangeKind =\n  | 'hired'\n  | 'ended'\n  | 'rehired'\n  | 'position-changed'\n  | 'worker-type-changed'\n  | 'leave-started'\n  | 'leave-ended'\n  | 'login-linked'\n  | 'login-unlinked';\n\n/**\n * What a qualification is. A `restriction` (for example \"youth worker\") limits\n * what its holder may do instead of permitting something.\n */\nexport type QualificationKind =\n  | 'ticket'\n  | 'certification'\n  | 'authorization'\n  | 'training'\n  | 'restriction';\n\n/**\n * Who a held qualification belongs to: the `person` (it survives a change of\n * employment) or the `employment` (it ends with it).\n */\nexport type QualificationScope = 'person' | 'employment';\n\n/** Stored held-qualification status. Expiry on a date is computed. */\nexport type HeldQualificationStatus =\n  | 'valid'\n  | 'expired'\n  | 'suspended'\n  | 'revoked';\n\n/** Kinds of dated change kept in a held qualification's history. */\nexport type HeldQualificationChangeKind =\n  | 'granted'\n  | 'renewed'\n  | 'suspended'\n  | 'reinstated'\n  | 'revoked'\n  | 'expired';\n\n/** Result of asking whether a profile is employed on a date. */\nexport type EmploymentCheck =\n  | { ok: true; employmentId: string; onLeave: boolean }\n  | { ok: false; reason: 'not-employed' | 'not-started' | 'ended' };\n\n/** Result of asking whether a profile holds a qualification on a date. */\nexport type QualificationCheck =\n  | { ok: true; heldQualificationId: string; expiresOn: IsoDate | null }\n  | {\n      ok: false;\n      reason:\n        | 'not-held'\n        | 'not-yet-issued'\n        | 'expired'\n        | 'suspended'\n        | 'revoked';\n    };\n\n/** Lifecycle events for an employment. */\nexport type EmploymentEventType =\n  | 'employment.hired'\n  | 'employment.ended'\n  | 'employment.rehired'\n  | 'employment.position-changed'\n  | 'employment.worker-type-changed'\n  | 'employment.leave-started'\n  | 'employment.leave-ended';\n\n/** Lifecycle events for a held qualification. */\nexport type HeldQualificationEventType =\n  | 'held-qualification.granted'\n  | 'held-qualification.renewed'\n  | 'held-qualification.suspended'\n  | 'held-qualification.reinstated'\n  | 'held-qualification.revoked'\n  | 'held-qualification.expired';\n\n/** Payload delivered to an {@link HrEventHandler}. */\nexport type HrEvent =\n  | {\n      type: EmploymentEventType;\n      employment: Employment;\n      /** The calendar date the change takes effect. */\n      effectiveOn: IsoDate;\n      at: Date;\n      byProfileId: string;\n    }\n  | {\n      type: HeldQualificationEventType;\n      heldQualification: HeldQualification;\n      effectiveOn: IsoDate;\n      at: Date;\n      byProfileId: string;\n    };\n\n/**\n * Event hook an application provides to react to HR changes (reminders are the\n * application's business). Called after the service's own transaction\n * commits. Delivery is best-effort: a throwing handler is logged and\n * swallowed, so it never rolls back a persisted change.\n *\n * \"After commit\" holds because a service only mutates through the root\n * database handle. A service constructed with a handle that is already inside\n * a transaction refuses every mutation (`HR_TRANSACTION_UNSUPPORTED`), so an\n * event is never delivered for rows an outer rollback could still remove.\n */\nexport type HrEventHandler = (event: HrEvent) => void | Promise<void>;\n\n/** Options shared by the HR services. */\nexport interface HrServiceOptions {\n  /**\n   * Optional lifecycle event hook, called after each mutation commits. The\n   * service must be constructed with the root database handle; see\n   * {@link HrEventHandler}.\n   */\n  onEvent?: HrEventHandler;\n}\n\n/** Stable error codes raised by this package. */\nexport type HrErrorCode =\n  | 'HR_INVALID'\n  | 'HR_NOT_FOUND'\n  | 'HR_ACTOR_INVALID'\n  | 'HR_TENANT_MISMATCH'\n  | 'HR_WRITE_FORBIDDEN'\n  | 'HR_HISTORY_IMMUTABLE'\n  | 'HR_STATUS_TRANSITION'\n  | 'HR_EMPLOYEE_NUMBER_TAKEN'\n  | 'HR_ALREADY_EMPLOYED'\n  | 'HR_TERM_OVERLAP'\n  | 'HR_QUALIFICATION_KEY_TAKEN'\n  | 'HR_ALREADY_HELD'\n  | 'HR_QUALIFICATION_SCOPE'\n  | 'HR_TRANSACTION_UNSUPPORTED';\n\n/** Base error for this package. `code` is stable and safe to branch on. */\nexport class HrError extends Error {\n  readonly code: HrErrorCode;\n\n  constructor(code: HrErrorCode, message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'HrError';\n    this.code = code;\n  }\n}\n"],"mappings":";AAqCO,IAAM,gCAGT;CACF,QAAQ,CAAC,YAAY,OAAO;CAC5B,YAAY,CAAC,UAAU,OAAO;CAC9B,OAAO,CAAC,QAAQ;AAClB;AAGO,IAAM,yBAAyB;CACpC;CACA;CACA;AACF;AAmJO,IAAM,UAAN,cAAsB,MAAM;CACxB;CAET,YAAY,MAAmB,SAAiB,SAAwB;EACtE,MAAM,SAAS,OAAO;EACtB,KAAK,OAAO;EACZ,KAAK,OAAO;CACd;AACF"}