@hotstaq/admin-panel 0.3.18 → 0.4.0

package/src/components/admin-detail-page.ts

@@ -0,0 +1,270 @@
+import { HotStaq, Hot, HotAPI, HotComponent, HotComponentOutput } from "hotstaq";
+
+/**
+ * Full-page detail chrome for an entity. Replaces the modal opened by
+ * <admin-edit hot-type="edit"> with a dedicated page (e.g. /budget/:id)
+ * that has its own back link, sections, and a sticky save bar at the
+ * bottom.
+ *
+ * The page is responsible for placing <admin-form-field>s inside the
+ * `<hot-place-here name="detailBody">` slot. This component handles:
+ *   - reading ?id from the URL
+ *   - GET'ing the entity via hot-get-url and populating form fields by
+ *     matching hot-field names against the response keys
+ *   - POST'ing values to hot-save-url on Save click
+ *   - DELETE'ing via hot-delete-url on Delete click (with confirm)
+ *   - showing a back link to hot-back-url
+ *
+ * Usage:
+ *   <admin-detail-page name="budgetDetail"
+ *                      hot-title="Budget"
+ *                      hot-back-url="/budgets"
+ *                      hot-back-text="← All budgets"
+ *                      hot-get-url="/v1/budgets/get"
+ *                      hot-save-url="/v1/budgets/edit"
+ *                      hot-delete-url="/v1/budgets/delete"
+ *                      hot-payload-key="budget"
+ *                      hot-jwt="${jwtToken}">
+ *     <admin-form-field hot-field="name" hot-label="Name" hot-required="1"></admin-form-field>
+ *     ...
+ *   </admin-detail-page>
+ */
+export class AdminDetailPage extends HotComponent
+{
+	/** Heading shown at the top of the page. */
+	title: string;
+	/** URL the back link points at. */
+	back_url: string;
+	/** Text on the back link. */
+	back_text: string;
+	/** GET-by-id endpoint. POSTed with { id: <id> }. */
+	get_url: string;
+	/** Edit/save endpoint. POSTed with { [payload_key]: { id, ...fields } }. */
+	save_url: string;
+	/** Optional delete endpoint. Hides the Delete button when blank. */
+	delete_url: string;
+	/** Wrapper key in the save payload (most DAO routes expect { budget: {...} } / { issue: {...} } etc). */
+	payload_key: string;
+	/** JWT bearer for the API calls. */
+	jwt: string;
+	/** URL query param that holds the entity id (default: "id"). */
+	id_param: string;
+	/** Save button text. */
+	save_text: string;
+	/** Delete button text. */
+	delete_text: string;
+	/** Confirmation prompt for delete. */
+	delete_confirm: string;
+
+	constructor (copy: HotComponent | HotStaq, api: HotAPI)
+	{
+		super (copy, api);
+
+		this.tag             = "admin-detail-page";
+		this.title           = "";
+		this.back_url        = "/";
+		this.back_text       = "← Back";
+		this.get_url         = "";
+		this.save_url        = "";
+		this.delete_url      = "";
+		this.payload_key     = "";
+		this.jwt             = "";
+		this.id_param        = "id";
+		this.save_text       = "Save";
+		this.delete_text     = "Delete";
+		this.delete_confirm  = "Are you sure you want to delete this?";
+	}
+
+	onPostPlace (parentHtmlElement: HTMLElement, htmlElement: HTMLElement): HTMLElement
+	{
+		const self = this;
+		const page = document.getElementById (this.name);
+		if (page == null) return (null);
+
+		const id = self.readIdFromUrl ();
+		if (!id)
+		{
+			self.showError (page, "No id provided in the URL.");
+			return (null);
+		}
+
+		// Wire buttons.
+		const saveBtn   = page.querySelector (".fl-detail-save") as HTMLButtonElement | null;
+		const deleteBtn = page.querySelector (".fl-detail-delete") as HTMLButtonElement | null;
+
+		if (saveBtn != null)
+			saveBtn.addEventListener ("click", (e) => { e.preventDefault (); self.handleSave (page, id); });
+
+		if (deleteBtn != null)
+			deleteBtn.addEventListener ("click", (e) => { e.preventDefault (); self.handleDelete (id); });
+
+		// Load existing record.
+		self.fetchAndFill (page, id);
+
+		return (null);
+	}
+
+	protected readIdFromUrl (): string
+	{
+		const params = new URLSearchParams (window.location.search);
+		return params.get (this.id_param) || "";
+	}
+
+	protected showError (page: HTMLElement, msg: string): void
+	{
+		const fb = page.querySelector (".fl-detail-feedback") as HTMLElement | null;
+		if (fb) { fb.className = "fl-detail-feedback alert alert-danger"; fb.textContent = msg; }
+	}
+
+	protected showSuccess (page: HTMLElement, msg: string): void
+	{
+		const fb = page.querySelector (".fl-detail-feedback") as HTMLElement | null;
+		if (fb)
+		{
+			fb.className = "fl-detail-feedback alert alert-success";
+			fb.textContent = msg;
+			setTimeout (() => { fb.className = "fl-detail-feedback d-none"; fb.textContent = ""; }, 2500);
+		}
+	}
+
+	protected async fetchAndFill (page: HTMLElement, id: string): Promise<void>
+	{
+		try
+		{
+			const headers: any = { "Content-Type": "application/json" };
+			if (this.jwt) headers["Authorization"] = "Bearer " + this.jwt;
+			const res = await fetch (this.get_url, {
+				method: "POST", headers: headers, body: JSON.stringify ({ id: id })
+			});
+			if (!res.ok) { this.showError (page, "Could not load: HTTP " + res.status); return; }
+			const obj = await res.json ();
+			if (obj == null) { this.showError (page, "Record not found."); return; }
+			this.populateFields (page, obj);
+		}
+		catch (ex)
+		{
+			this.showError (page, "Could not load: " + (ex as Error).message);
+		}
+	}
+
+	protected populateFields (page: HTMLElement, obj: any): void
+	{
+		const nodes = page.querySelectorAll ("[hot-field]");
+		for (let i = 0; i < nodes.length; i++)
+		{
+			const el = nodes[i] as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+			const field = el.getAttribute ("hot-field");
+			if (field == null || field === "") continue;
+			const val = obj[field];
+			if (val == null) continue;
+			if (el instanceof HTMLInputElement && el.type === "checkbox")
+				el.checked = val === true || val === "true" || val === 1;
+			else
+				el.value = String (val);
+		}
+	}
+
+	protected collectValues (page: HTMLElement): any
+	{
+		const out: any = {};
+		const nodes = page.querySelectorAll ("[hot-field]");
+		for (let i = 0; i < nodes.length; i++)
+		{
+			const el = nodes[i] as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+			const field = el.getAttribute ("hot-field");
+			if (field == null || field === "") continue;
+			if (el instanceof HTMLInputElement && el.type === "checkbox")
+				out[field] = el.checked;
+			else if (el instanceof HTMLInputElement && el.type === "number")
+				out[field] = el.value === "" ? null : Number (el.value);
+			else
+				out[field] = el.value;
+		}
+		return out;
+	}
+
+	protected async handleSave (page: HTMLElement, id: string): Promise<void>
+	{
+		const values = this.collectValues (page);
+		values.id = id;
+		const body: any = this.payload_key ? { [this.payload_key]: values } : values;
+
+		const btn = page.querySelector (".fl-detail-save") as HTMLButtonElement | null;
+		if (btn) btn.disabled = true;
+		try
+		{
+			const headers: any = { "Content-Type": "application/json" };
+			if (this.jwt) headers["Authorization"] = "Bearer " + this.jwt;
+			const res = await fetch (this.save_url, {
+				method: "POST", headers: headers, body: JSON.stringify (body)
+			});
+			if (!res.ok)
+			{
+				let msg = "HTTP " + res.status;
+				try { const j = await res.json (); if (j && j.error) msg = j.error; } catch (e) {}
+				this.showError (page, "Save failed: " + msg);
+				return;
+			}
+			this.showSuccess (page, "Saved.");
+		}
+		catch (ex)
+		{
+			this.showError (page, "Save failed: " + (ex as Error).message);
+		}
+		finally
+		{
+			if (btn) btn.disabled = false;
+		}
+	}
+
+	protected async handleDelete (id: string): Promise<void>
+	{
+		if (!window.confirm (this.delete_confirm)) return;
+		try
+		{
+			const headers: any = { "Content-Type": "application/json" };
+			if (this.jwt) headers["Authorization"] = "Bearer " + this.jwt;
+			const res = await fetch (this.delete_url, {
+				method: "POST", headers: headers, body: JSON.stringify ({ id: id })
+			});
+			if (!res.ok) { alert ("Delete failed: HTTP " + res.status); return; }
+			window.location.href = this.back_url;
+		}
+		catch (ex)
+		{
+			alert ("Delete failed: " + (ex as Error).message);
+		}
+	}
+
+	output (): string | HotComponentOutput[]
+	{
+		if (this.name === "")
+			throw new Error ("admin-detail-page: id (name) is required");
+		if (this.get_url === "" || this.save_url === "")
+			throw new Error ("admin-detail-page: hot-get-url and hot-save-url are required");
+
+		const deleteBtn = this.delete_url
+			? `<button type="button" class="btn btn-outline-danger fl-detail-delete">${this.delete_text}</button>`
+			: "";
+
+		return (`
+			<div id="${this.name}" class="fl-detail-page">
+				<div class="container" style="max-width:880px;padding:1.5rem 1rem 7rem;">
+					<div class="mb-3"><a href="${this.back_url}" class="text-muted small text-decoration-none">${this.back_text}</a></div>
+					<h1 class="h3 mb-3">${this.title}</h1>
+					<div class="fl-detail-feedback d-none"></div>
+					<div class="card mb-3"><div class="card-body">
+						<div class="row g-3">
+							<hot-place-here name="detailBody"></hot-place-here>
+						</div>
+					</div></div>
+				</div>
+				<div class="fl-detail-save-bar">
+					<div class="container d-flex justify-content-between align-items-center" style="max-width:880px;">
+						${deleteBtn}
+						<button type="button" class="btn btn-primary fl-detail-save ms-auto">${this.save_text}</button>
+					</div>
+				</div>
+			</div>`);
+	}
+}

package/src/components/admin-disclaimer.ts

@@ -0,0 +1,43 @@
+import { HotStaq, Hot, HotAPI, HotComponent, HotComponentOutput } from "hotstaq";
+
+/**
+ * Pinned info card — short headline + body text, indigo left border.
+ * Pattern lifted from the DonorTiers "No governance influence"
+ * disclaimer on /donorTiers. Useful for "no influence", "draft only",
+ * "internal use", etc. notes that belong above the main content.
+ *
+ * Usage:
+ *   <admin-disclaimer hot-heading="Disclaimer">
+ *     The body text of the disclaimer goes here.
+ *   </admin-disclaimer>
+ */
+export class AdminDisclaimer extends HotComponent
+{
+	/** Heading (h2.h6). */
+	heading: string;
+	/** Accent color for the left border. */
+	accent: string;
+
+	constructor (copy: HotComponent | HotStaq, api: HotAPI)
+	{
+		super (copy, api);
+
+		this.tag     = "admin-disclaimer";
+		this.heading = "";
+		this.accent  = "#4f46e5";
+	}
+
+	output (): string | HotComponentOutput[]
+	{
+		const heading = this.heading ? `<h2 class="h6 mb-2" style="letter-spacing:0.02em;">${this.heading}</h2>` : "";
+		return `
+			<div class="card fl-disclaimer mb-3" style="border-left:4px solid ${this.accent};">
+				<div class="card-body">
+					${heading}
+					<div class="mb-0 text-muted" style="font-size:0.9rem;line-height:1.45;">
+						${this.inner || ""}
+					</div>
+				</div>
+			</div>`;
+	}
+}

package/src/components/admin-eyebrow-heading.ts

@@ -0,0 +1,50 @@
+import { HotStaq, Hot, HotAPI, HotComponent, HotComponentOutput } from "hotstaq";
+
+/**
+ * A page heading with a small uppercase "eyebrow" label above it.
+ * Pattern lifted from the /live page on Freelight — the "Live Campaign
+ * Page" label above the candidate name.
+ *
+ * Usage:
+ *   <admin-eyebrow-heading hot-eyebrow="Campaign Project"
+ *                          hot-heading="Q4 Outreach Plan"></admin-eyebrow-heading>
+ */
+export class AdminEyebrowHeading extends HotComponent
+{
+	/** The small uppercase label rendered above the heading. */
+	eyebrow: string;
+	/** The h1 text. */
+	heading: string;
+	/** Optional muted subtitle rendered below the heading. */
+	subtitle: string;
+	/** "center" | "start" (default). */
+	align: string;
+
+	constructor (copy: HotComponent | HotStaq, api: HotAPI)
+	{
+		super (copy, api);
+
+		this.tag      = "admin-eyebrow-heading";
+		this.eyebrow  = "";
+		this.heading  = "";
+		this.subtitle = "";
+		this.align    = "start";
+	}
+
+	output (): string | HotComponentOutput[]
+	{
+		const alignClass = this.align === "center" ? "text-center" : "";
+		const eyebrow = this.eyebrow
+			? `<div class="text-uppercase text-muted small mb-2" style="letter-spacing:0.08em;">${this.eyebrow}</div>`
+			: "";
+		const subtitle = this.subtitle
+			? `<p class="text-muted mb-0">${this.subtitle}</p>`
+			: "";
+		return `
+			<div class="fl-eyebrow-heading mb-3 ${alignClass}">
+				${eyebrow}
+				<h1 class="h3 mb-1">${this.heading || this.inner || ""}</h1>
+				${subtitle}
+			</div>`;
+	}
+}

package/src/components/admin-form-field.ts

@@ -0,0 +1,166 @@
+import { HotStaq, Hot, HotAPI, HotComponent, HotComponentOutput } from "hotstaq";
+
+/**
+ * A labeled form field. Wraps a single <input>, <select>, or <textarea>
+ * with a proper <label>, an optional required-marker, and helper text.
+ *
+ * Replaces the boilerplate of hand-rolling label + input + small help
+ * div across every Add/Edit form. Inspired by the Freelight pages
+ * (volunteers.hott, yard-signs.hott, members.hott) where every field
+ * already follows this pattern.
+ *
+ * Usage:
+ *   <admin-form-field hot-field="name" hot-label="First name" hot-required="1"
+ *                     hot-placeholder="e.g. Jane" hot-autocomplete="given-name">
+ *   </admin-form-field>
+ *
+ *   <admin-form-field hot-field="status" hot-label="Status" hot-control="select"
+ *                     hot-options="active,suspended,invited"></admin-form-field>
+ *
+ *   <admin-form-field hot-field="description" hot-label="Description"
+ *                     hot-control="textarea" hot-rows="3"
+ *                     hot-help="Shown on the public page."></admin-form-field>
+ */
+export class AdminFormField extends HotComponent
+{
+	/** The field name (used for hot-field and the label's `for` attribute). */
+	field: string;
+	/** The visible label text. */
+	label: string;
+	/** "1" / "true" to render the red required marker after the label. */
+	required: string;
+	/** input type when control is "input" (text, email, tel, number, date, etc). */
+	type: string;
+	/** Control kind: "input" (default) | "select" | "textarea" | "checkbox". */
+	control: string;
+	/** Placeholder text (ignored for type=date / control=select / checkbox). */
+	placeholder: string;
+	/** Autocomplete attribute value (given-name, email, tel, street-address, etc). */
+	autocomplete: string;
+	/** Small helper text shown below the input. */
+	help: string;
+	/** Comma-separated options when control="select". Each item can be "value:label" or just "value". */
+	options: string;
+	/** Rows for control="textarea". */
+	rows: string;
+	/** Minimum value for type=number. */
+	min: string;
+	/** Step for type=number. */
+	step: string;
+	/** Max length for input/textarea. */
+	maxlength: string;
+	/** Bootstrap column class for grid use, e.g. "col-md-6". Empty => no wrapper col. */
+	col: string;
+	/** Size: "sm" (default in the new theme) | "md". */
+	size: string;
+	/** Extra CSS classes for the input element itself. */
+	css_class: string;
+
+	constructor (copy: HotComponent | HotStaq, api: HotAPI)
+	{
+		super (copy, api);
+
+		this.tag           = "admin-form-field";
+		this.field         = "";
+		this.label         = "";
+		this.required      = "0";
+		this.type          = "text";
+		this.control       = "input";
+		this.placeholder   = "";
+		this.autocomplete  = "";
+		this.help          = "";
+		this.options       = "";
+		this.rows          = "3";
+		this.min           = "";
+		this.step          = "";
+		this.maxlength     = "";
+		this.col           = "";
+		this.size          = "sm";
+		this.css_class     = "";
+	}
+
+	/**
+	 * Field renders inside the surrounding flow — no modal-body-relocation
+	 * trick like admin-text does. The new components are designed for
+	 * detail pages and inline add panels, not modals.
+	 */
+	onPostPlace (parentHtmlElement: HTMLElement, htmlElement: HTMLElement): HTMLElement
+	{
+		return (null);
+	}
+
+	private renderInput (id: string, sizeClass: string, classes: string): string
+	{
+		const minAttr  = this.min  ? ` min="${this.min}"`  : "";
+		const stepAttr = this.step ? ` step="${this.step}"` : "";
+		const maxAttr  = this.maxlength ? ` maxlength="${this.maxlength}"` : "";
+		const acAttr   = this.autocomplete ? ` autocomplete="${this.autocomplete}"` : "";
+		const phAttr   = (this.type === "date" || this.placeholder === "")
+			? "" : ` placeholder="${this.placeholder.replace (/"/g, "&quot;")}"`;
+		return `<input id="${id}" hot-field="${this.field}" type="${this.type}" class="form-control${sizeClass}${classes}"${minAttr}${stepAttr}${maxAttr}${acAttr}${phAttr} />`;
+	}
+
+	private renderSelect (id: string, sizeClass: string, classes: string): string
+	{
+		const opts = (this.options || "").split (",").map ((raw) =>
+			{
+				const part = raw.trim ();
+				if (part === "") return "";
+				const colon = part.indexOf (":");
+				const val   = colon >= 0 ? part.slice (0, colon) : part;
+				const lbl   = colon >= 0 ? part.slice (colon + 1) : part;
+				return `<option value="${val.replace (/"/g, "&quot;")}">${lbl}</option>`;
+			}).join ("");
+		return `<select id="${id}" hot-field="${this.field}" class="form-select${sizeClass}${classes}">${opts}</select>`;
+	}
+
+	private renderTextarea (id: string, sizeClass: string, classes: string): string
+	{
+		const phAttr = this.placeholder ? ` placeholder="${this.placeholder.replace (/"/g, "&quot;")}"` : "";
+		const maxAttr = this.maxlength ? ` maxlength="${this.maxlength}"` : "";
+		return `<textarea id="${id}" hot-field="${this.field}" rows="${this.rows}" class="form-control${sizeClass}${classes}"${maxAttr}${phAttr}></textarea>`;
+	}
+
+	private renderCheckbox (id: string): string
+	{
+		return `<div class="form-check"><input id="${id}" hot-field="${this.field}" type="checkbox" class="form-check-input" /><label for="${id}" class="form-check-label">${this.label}</label></div>`;
+	}
+
+	output (): string | HotComponentOutput[]
+	{
+		if (this.field === "")
+			throw new Error ("admin-form-field: hot-field is required");
+
+		const id        = `ff-${this.field}-${Math.random ().toString (36).slice (2, 7)}`;
+		const sizeClass = this.size === "sm" ? " form-control-sm" : "";
+		const classes   = this.css_class ? " " + this.css_class : "";
+
+		// Checkbox is a special case — the label sits next to the box,
+		// not above. Skip the rest of the wrapping.
+		if (this.control === "checkbox")
+		{
+			const inner = this.renderCheckbox (id);
+			return (this.col ? `<div class="${this.col}">${inner}</div>` : inner);
+		}
+
+		let control = "";
+		if (this.control === "select")        control = this.renderSelect   (id, sizeClass, classes);
+		else if (this.control === "textarea") control = this.renderTextarea (id, sizeClass, classes);
+		else                                  control = this.renderInput    (id, sizeClass, classes);
+
+		const requiredMarker = (this.required === "1" || this.required === "true")
+			? ` <span class="text-danger" aria-label="required">*</span>`
+			: "";
+
+		const helpHtml = this.help
+			? `<div class="form-text small">${this.help}</div>`
+			: "";
+
+		const fieldHtml = `
+			<label for="${id}" class="form-label small mb-1">${this.label}${requiredMarker}</label>
+			${control}
+			${helpHtml}`;
+
+		return (this.col ? `<div class="${this.col}">${fieldHtml}</div>` : `<div>${fieldHtml}</div>`);
+	}
+}

package/src/index.ts

@@ -7,6 +7,16 @@ import { AdminTableField } from "./components/admin-table-field";
 import { AdminTableRow } from "./components/admin-table-row";
 import { AdminText } from "./components/admin-text";
 
+// admin-panel 0.4.0 — Freelight-style components. Backwards compatible
+// with the existing modal/table set above; pages opt in by switching
+// their .hott templates to use the new tags.
+import { AdminFormField } from "./components/admin-form-field";
+import { AdminAddPanel } from "./components/admin-add-panel";
+import { AdminCardTable } from "./components/admin-card-table";
+import { AdminDetailPage } from "./components/admin-detail-page";
+import { AdminDisclaimer } from "./components/admin-disclaimer";
+import { AdminEyebrowHeading } from "./components/admin-eyebrow-heading";
+
 export {
 		AdminButton,
 		AdminDropdown,
@@ -15,5 +25,11 @@ export {
 		AdminTable,
 		AdminTableField,
 		AdminTableRow,
-		AdminText
-	};
+		AdminText,
+		AdminFormField,
+		AdminAddPanel,
+		AdminCardTable,
+		AdminDetailPage,
+		AdminDisclaimer,
+		AdminEyebrowHeading
+	};