@webx-ui/module-vacancies 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webx-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @webx-ui/module-vacancies
+
+The front end of the vacancies section of the [WebX UI](https://github.com/webx-ui/webx-ui) admin
+panel: who the organisation is looking for — where and how, the terms and the pay, the duties, the
+requirements and what is offered — and the categories they are grouped under.
+
+The other half is the Composer package `webx-ui/module-vacancies`, which owns the vacancies, their
+pages and addresses, the `JobPosting` markup, `vacancies()` for templates and the API. A section
+appears in the panel when both halves are installed.
+
+## Install
+
+```bash
+npm install @webx-ui/module-vacancies
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { vacancies } from '@webx-ui/module-vacancies'
+import '@webx-ui/module-vacancies/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [...vacancies()],
+}).mount()
+```
+
+`vacancies()` answers with two sections — the vacancies and their categories — because the panel
+draws one entry per module. The server puts both in the `vacancies` group.
+`vacancies({ path: '/careers' })` puts them somewhere else inside the panel.
+
+## What is here
+
+- **The list** — every vacancy at once, in the order the site lists them, with tabs: the open ones
+  (the default), the closed ones, all — the closed ones dimmed, marked «Closed» or «Expired» — and
+  the bin. The order is dragged by a handle, or with the keyboard on it, on «Open» and «All» while
+  nothing narrows the list; the line under the rows says why when it cannot be. The category and
+  the state are behind the funnel. «Duplicate» and «Close the hiring» / «Reopen» are in the row
+  menu.
+- **The editor** — the described screen `vacancies.form` with the tabs Vacancy · Settings · SEO ·
+  History, autosaved into a draft and guarded by a revision. «Open until» and «Posted on» are
+  calendar days (`YYYY-MM-DD`) and read the same day in every zone. «Duplicate» in the bar saves,
+  copies and opens the copy. The categories, the application form and «closed» wait in the draft and
+  reach the site on «Publish». A project adds its own fields with a patch into the
+  `project-fields` card.
+- **Categories** — the panel's shared category screens (`categoryRoutes`): groups with a key for
+  the site's filter, no page of their own. `vacancyCategoriesOptions()` is exported for a panel
+  that mounts them elsewhere.
+
+The words are English by default and come from the server in the panel's language
+(`webx-vacancies::`).
+
+Documentation: https://webx-ui.github.io/webx-ui/guide/vacancies.html
+
+## License
+
+MIT

package/dist/VacanciesPage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Every vacancy at once, in the order the site lists them (§4.10).
+ *
+ * The shape of the recipes, with the tabs of the events: no paginator, because this is where the
+ * order is dragged and a drag cannot cross a page — a site has tens of vacancies, not thousands.
+ * The tabs are *open or closed*, not the state: the open ones are what the site lists and what an
+ * editor comes here for, so they are the list with nothing chosen. "All" draws the closed ones
+ * muted, so the line between the two can be seen at a glance; the category, the state and the
+ * search narrow any of them.
+ *
+ * One order, and only one (§4.11). The grips are there on "Open" and "All" while nothing narrows
+ * the list — a selection has invisible gaps in it, and a closed vacancy is on no list of the site,
+ * so ordering the "Closed" tab would be ordering nothing. The line under the rows says which of
+ * the three it is.
+ */
+type __VLS_Props = {
+    base?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    base: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/VacancyCreateDialog.d.ts

@@ -0,0 +1,4 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {
+    field: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/VacancyEditorPage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The editor of one vacancy: a head that stays put, the described screen under it, and the bar
+ * along the bottom where it is saved, duplicated and published (§4.10).
+ *
+ * Everything between the head and the bar is `vacancies.form` — the vacancy, its settings, the SEO
+ * card `module-seo` patches on and the history — so a project adds its own field with a patch
+ * rather than a fork of this file. Saving is by autosave into the draft, and the draft carries
+ * the categories, the form and "closed" too: the site changes, all of it at once, only on
+ * "Publish". Edits are guarded by a revision: a save over somebody else's is refused with a 409
+ * and the question of which version the site gets.
+ *
+ * The two dates are calendar days, not moments (decision 13): the pickers hold `YYYY-MM-DD` as
+ * written, and the head prints them from their parts (`days.ts`), so no zone moves them.
+ */
+type __VLS_Props = {
+    base?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    base: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/VacancyHistory.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLDivElement>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,47 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { VacanciesList, VacancyDetail, VacancyInput, VacancyQuery, VacancyRow, VacancySave, VacancyVersion } from './types';
+export interface VacanciesApi {
+    /** Every vacancy the query asks for, with what the list can be narrowed by. */
+    list(query?: VacancyQuery): Promise<VacanciesList>;
+    /** One vacancy as its editor opens it: the record, the screen's values and the revision. */
+    get(id: number): Promise<VacancyDetail>;
+    /** A new vacancy, made in one transaction: a refused address leaves no bare row behind. */
+    create(input: VacancyInput): Promise<VacancyDetail>;
+    /**
+     * Save the draft. Refused with a 409 when the revision is stale — the body is a
+     * {@link VacancyConflict} with the vacancy as it now is.
+     */
+    save(id: number, input: VacancySave): Promise<VacancyDetail>;
+    /** Throw away what is waiting and keep what the site is showing. */
+    discard(id: number): Promise<VacancyDetail>;
+    /**
+     * A copy as a draft that was never published (decision 20): every field, the categories and
+     * the form, the same title and an address with the next free suffix, right after the original.
+     * The answer is the copy's form, so the editor can open it straight away.
+     */
+    duplicate(id: number): Promise<VacancyDetail>;
+    publish(id: number): Promise<VacancyRow>;
+    unpublish(id: number): Promise<VacancyRow>;
+    /**
+     * The hiring is over, before its last day — or it is on again. A publication of its own on the
+     * server (`is_closed` is published with everything else), so it is refused with a 409 while
+     * edits are waiting: closing would put them on the site too.
+     */
+    close(id: number): Promise<VacancyRow>;
+    reopen(id: number): Promise<VacancyRow>;
+    remove(id: number): Promise<void>;
+    restore(id: number): Promise<VacancyRow>;
+    /** The order on screen, written as a whole. There is one order and only one. */
+    reorder(ids: number[]): Promise<void>;
+    /** The publications, newest first. */
+    versions(id: number): Promise<VacancyVersion[]>;
+    /** An old publication becomes the draft; putting it on the site is a separate step. */
+    restoreVersion(id: number, number: number): Promise<VacancyDetail>;
+}
+/** The path of the list under the panel's API. */
+export declare const VACANCIES_API = "vacancies";
+/**
+ * Everything under `/vacancies`, below the panel's API path (§4.11) — except the categories, which
+ * are the panel's shared category API under `vacancies/categories`.
+ */
+export declare function createVacanciesApi(admin: AdminContext): VacanciesApi;

package/dist/days.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A vacancy's dates are calendar days (decision 13): `valid_through` is the last day it is open,
+ * `posted_at` the day it was first put up, both `YYYY-MM-DD` with no time and no zone.
+ *
+ * Nothing here may turn such a day into a moment. `new Date('2026-11-30')` is midnight *UTC*, and
+ * west of Greenwich that is still the 29th — the column would print the day before the one the
+ * editor picked, and the site (which reads the day as written) would disagree with the panel. So
+ * the day is built from its parts, at local midnight, and formatted from there: the same three
+ * numbers in every zone.
+ *
+ * The pickers of `vacancies.form` do the same by themselves: `valueFormat: "yyyy-MM-dd"` parses
+ * and formats in the browser's own zone, so a day goes in and comes out unchanged.
+ */
+/** The day as a local date, or `null` for anything that is not a `YYYY-MM-DD`. */
+export declare function dayOf(value: string | null | undefined): Date | null;
+/**
+ * The day in the panel's language — "30 Nov", and with the year when it is not this one. Empty
+ * for no day at all.
+ */
+export declare function formatDay(value: string | null | undefined, locale: string, now?: Date): string;
+/** The same day, in full — for a tip and for the head of the editor. */
+export declare function longDay(value: string | null | undefined, locale: string): string;

package/dist/editor.d.ts

@@ -0,0 +1,19 @@
+import { InjectionKey, Ref } from 'vue';
+import { VacancyRow } from './types';
+/**
+ * What the editor knows and the nodes of `vacancies.form` do not: the vacancy being edited, and a
+ * way to read it again. The history needs both — its list is keyed by the vacancy, and a restored
+ * version has to reach the fields the form is bound to.
+ */
+export interface VacancyEditorContext {
+    /** The vacancy as the server last answered it, or `null` while the first request is out. */
+    vacancy: Ref<VacancyRow | null>;
+    /** Whether this administrator may write at all. */
+    canManage: boolean;
+    /** Ask the server for the vacancy again — after a restore, a publication, a discard. */
+    reload(): Promise<void>;
+}
+export declare const vacancyEditorKey: InjectionKey<VacancyEditorContext>;
+export declare function provideVacancyEditor(editor: VacancyEditorContext): void;
+/** The editor above this node, or `null` outside one — a demo or a test draws nothing. */
+export declare function useVacancyEditor(): VacancyEditorContext | null;

package/dist/i18n.d.ts

@@ -0,0 +1,2 @@
+/** Puts this package's English under the panel's dictionary, once per panel. */
+export declare function useVacanciesMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { vacancies, vacancyCategoriesOptions, type VacanciesOptions } from './module';
+export { createVacanciesApi, VACANCIES_API, type VacanciesApi } from './api';
+export { vacanciesMessages } from './messages';
+export { provideVacancyEditor, vacancyEditorKey, useVacancyEditor, type VacancyEditorContext, } from './editor';
+export { default as WxVacanciesPage } from './VacanciesPage';
+export { default as WxVacancyCreateDialog } from './VacancyCreateDialog';
+export { default as WxVacancyEditorPage } from './VacancyEditorPage';
+export { default as WxVacancyHistory } from './VacancyHistory';
+export type { VacanciesList, VacancyClosedReason, VacancyConflict, VacancyDetail, VacancyInput, VacancyQuery, VacancyRow, VacancySave, VacancyState, VacancyStatus, VacancyTermRef, VacancyVersion, VacancyWorkplace, } from './types';