@kahitsan/ksui 0.3.0 → 0.4.0

package/src/index.ts

@@ -1,4 +1,4 @@
-// @kahitsan/ksui — shared SolidJS UI components for KahitSan/Hilinga plugins.
+// @kahitsan/ksui: shared SolidJS UI components for KahitSan/Hilinga plugins.
 //
 // These were copied byte-for-byte across plugins (counter, transactions, ...);
 // this package is the single canonical copy, PUBLISHED to GitHub Packages and
@@ -7,28 +7,25 @@
 // The package ships its source under a `solid` export condition (see
 // package.json), so the consumer's vite-plugin-solid compiles these components
 // while solid-js and `@kserp/host-ui` stay EXTERNALIZED to the host runtime
-// globals — the plugin IIFE bundles them identically to a local copy: no runtime
+// globals. The plugin IIFE bundles them identically to a local copy: no runtime
 // change, single Solid instance, host UI kit reused. The `@kserp/host-ui` ambient
 // type contract ships alongside (host-ui.d.ts, the `./host-ui` export).
+//
+// Components live under two folders by category:
+//   base/      a primitive that stands on its own. It uses only solid-js,
+//              lucide-solid, and/or the host kit via "@kserp/host-ui". It does
+//              not import another ksui component.
+//   composite/ a component that wraps a base or composes two or more components
+//              into a higher-level widget.
+// See CONTRIBUTING.md for the placement rule when adding a new component.
 
-export { default as MentionTextarea } from "./components/MentionTextarea";
-export type { MentionTextareaProps } from "./components/MentionTextarea";
-
-export { default as MarkdownNotes } from "./components/MarkdownNotes";
-export type { MarkdownNotesProps } from "./components/MarkdownNotes";
-
-export { default as ClientPicker } from "./components/ClientPicker";
-export type { ClientOption } from "./components/ClientPicker";
-
-export { default as VoucherPicker, calculateDiscount } from "./components/VoucherPicker";
-export type { VoucherOption } from "./components/VoucherPicker";
-
-export { default as CameraCapture } from "./components/CameraCapture";
+// ---------------------------------------------------------------------------
+// Base components
+// ---------------------------------------------------------------------------
 
-export { default as AddAttachmentTile } from "./components/AddAttachmentTile";
+export { default as CameraCapture } from "./components/base/CameraCapture";
 
-export { default as PaymentAccountPicker } from "./components/PaymentAccountPicker";
-export type { PaymentAccountOption } from "./components/PaymentAccountPicker";
+export { default as AddAttachmentTile } from "./components/base/AddAttachmentTile";
 
 // The canonical account + attachment widget set: AccountAvatar (logo / type-icon
 // glyph / initial-on-color fallback, with its initials + color + SVG helpers)
@@ -41,22 +38,82 @@ export {
   getInitials,
   getAvatarColor,
   buildInitialsSvg,
-} from "./components/AccountAvatar";
-export type { AvatarAccount } from "./components/AccountAvatar";
+} from "./components/base/AccountAvatar";
+export type { AvatarAccount } from "./components/base/AccountAvatar";
+
+export { default as ExistingAttachmentTile } from "./components/base/ExistingAttachmentTile";
+export type { ExistingAttachment } from "./components/base/ExistingAttachmentTile";
+
+// Plugin consolidation: widgets that were duplicated across plugins
+// (form fields, detail rows, tooltips, progress/legend display, image cropping)
+// promoted into the single canonical package.
+export { default as FormField } from "./components/base/FormField";
+export { default as DetailRow } from "./components/base/DetailRow";
+export { default as Tooltip } from "./components/base/Tooltip";
+export { default as ImageCropper } from "./components/base/ImageCropper";
+export { default as ProgressBar, type ProgressBarProps } from "./components/base/ProgressBar";
+export { default as ChartLegend } from "./components/base/ChartLegend";
+
+// Plugin reusability backlog: atoms migrated from per-plugin copies into the
+// single canonical package.
+export { default as StatusPill, type StatusTone } from "./components/base/StatusPill";
+export { default as SegmentedFilter, type SegmentedFilterOption } from "./components/base/SegmentedFilter";
+export { default as CopyButton } from "./components/base/CopyButton";
+export { default as KpiCard, type KpiCardProps, type KpiTone } from "./components/base/KpiCard";
+export { default as RadioCardGroup } from "./components/base/RadioCardGroup";
+export { default as FormErrorBanner } from "./components/base/FormErrorBanner";
+export { default as TagPill } from "./components/base/TagPill";
+
+// ---------------------------------------------------------------------------
+// Composite components
+// ---------------------------------------------------------------------------
+
+// PaymentAccountPicker composes AccountAvatar inside a searchable dropdown.
+export { default as PaymentAccountPicker } from "./components/composite/PaymentAccountPicker";
+export type { PaymentAccountOption } from "./components/composite/PaymentAccountPicker";
+
+// LiveTimer wraps ProgressBar with timer state and elapsed-time display.
+export { default as LiveTimer, type LiveTimerProps } from "./components/composite/LiveTimer";
+
+// Plugin reusability backlog: composites migrated from per-plugin copies.
+export { default as SecretReveal, type SecretRevealProps } from "./components/composite/SecretReveal";
+export { default as FormActions, type FormActionsProps } from "./components/composite/FormActions";
+
+// Higher-level widgets: the search-and-create pickers and the mention-aware
+// editor that the team treats as composites.
+export { default as MentionTextarea } from "./components/composite/MentionTextarea";
+export type { MentionTextareaProps } from "./components/composite/MentionTextarea";
+
+export { default as MarkdownNotes } from "./components/composite/MarkdownNotes";
+export type { MarkdownNotesProps } from "./components/composite/MarkdownNotes";
+
+export { default as ClientPicker } from "./components/composite/ClientPicker";
+export type { ClientOption } from "./components/composite/ClientPicker";
+
+export { default as VoucherPicker, calculateDiscount } from "./components/composite/VoucherPicker";
+export type { VoucherOption } from "./components/composite/VoucherPicker";
+
+// ---------------------------------------------------------------------------
+// Utils (not components)
+// ---------------------------------------------------------------------------
 
 export {
   getAccountIcon,
   getAccountTone,
   ACCOUNT_ICON_SLUGS,
   ACCOUNT_ICON_LABELS,
-} from "./lib/account-icons";
-export type { IconComponent, AccountIconSlug } from "./lib/account-icons";
+} from "./utils/account-icons";
+export type { IconComponent, AccountIconSlug } from "./utils/account-icons";
+
+export { buildLogoSrc } from "./utils/account-logo-url";
 
-export { buildLogoSrc } from "./lib/account-logo-url";
+export { attachmentUrl, isResolvableAttachment } from "./utils/attachments";
 
-export { attachmentUrl, isResolvableAttachment } from "./lib/attachments";
+export { useAccountsIndex, resolveAccount, resolveAccountName } from "./utils/accounts-index";
 
-export { default as ExistingAttachmentTile } from "./components/ExistingAttachmentTile";
-export type { ExistingAttachment } from "./components/ExistingAttachmentTile";
+export { INPUT_CLASS } from "./utils/INPUT_CLASS";
 
-export { useAccountsIndex, resolveAccount, resolveAccountName } from "./lib/accounts-index";
+// Plugin reusability backlog: formatting helpers migrated from per-plugin copies.
+export { formatPHP } from "./utils/formatPHP";
+export { formatShortDate } from "./utils/formatShortDate";
+export { formatFullDate } from "./utils/formatFullDate";

package/src/utils/INPUT_CLASS.ts

@@ -0,0 +1,7 @@
+// Shared Tailwind class string for text inputs across plugin forms: a
+// full-width rounded input with the dark zinc surface and the amber focus
+// ring. Copied verbatim from the packages remote UI atoms so the shared kit
+// owns the single source of truth. Pure string constant, no dependencies.
+
+export const INPUT_CLASS =
+  "w-full rounded-lg border border-zinc-700 bg-zinc-800/50 px-3 py-2 text-sm text-zinc-200 focus:border-amber-500/50 focus:outline-none";

package/src/{lib → utils}/account-logo-url.ts

@@ -6,7 +6,7 @@
 
 export function buildLogoSrc(s3Link: string | null | undefined): string {
   // The value flows straight into <img src>, so only an http(s) URL is allowed
-  // through — a stored javascript:/data:/vbscript: scheme would be stored XSS.
+  // through. A stored javascript:/data:/vbscript: scheme would be stored XSS.
   if (s3Link && /^https?:/i.test(s3Link)) return s3Link;
   return "";
 }

package/src/{lib → utils}/accounts-index.tsx

@@ -12,12 +12,12 @@
 // (read from the host's useActiveWorkspace()). Because plugin-ui ships as source
 // compiled into each plugin's IIFE, the module-level singleton stays per-plugin.
 // Degrades gracefully: when the financial-accounts plugin isn't deployed the
-// fetch 404s/fails and the index stays empty — resolveAccount() then falls back
+// fetch 404s/fails and the index stays empty, so resolveAccount() then falls back
 // to the type-default glyph.
 
 import { createResource, type Resource } from "solid-js";
 import { useActiveWorkspace } from "@kserp/host-ui";
-import type { AvatarAccount } from "../components/AccountAvatar";
+import type { AvatarAccount } from "../components/base/AccountAvatar";
 
 interface IndexShape {
   byId: Map<number | string, AvatarAccount>;

package/src/{lib → utils}/attachments.ts

@@ -1,19 +1,19 @@
 // Attachment URL resolver for plugin remotes.
 //
 // Attachments are object-storage only: the upload route stores the public S3
-// URL in s3_link, which is the sole reference — the legacy on-disk file_path
+// URL in s3_link, which is the sole reference. The legacy on-disk file_path
 // column and the kernel /assets/ fallback are gone.
 
 export function attachmentUrl(s3Link: string | null | undefined): string {
   // The value flows straight into <a href> / <img src>, so only an http(s) URL
-  // is allowed through — a stored javascript:/data:/vbscript: scheme would be
+  // is allowed through. A stored javascript:/data:/vbscript: scheme would be
   // stored XSS. Every attachment has a valid https s3_link; anything else
   // yields an empty src and the render site shows an "unavailable" placeholder.
   if (s3Link && /^https?:/i.test(s3Link)) return s3Link;
   return "";
 }
 
-// Whether an attachment can actually be fetched — true only for a safe http(s)
+// Whether an attachment can actually be fetched, true only for a safe http(s)
 // s3_link. Render sites show an "unavailable" placeholder otherwise.
 export function isResolvableAttachment(s3Link: string | null | undefined): boolean {
   return !!s3Link && /^https?:/i.test(s3Link);

package/src/utils/formatFullDate.ts

@@ -0,0 +1,14 @@
+// Canonical date+time formatter for the en-PH locale.
+//
+// Pure helper, no rendering and no domain coupling. Renders a parsed timestamp
+// as "Mon D, YYYY · h:mm AM" using the platform Intl/Date globals. Returns the
+// em-dash placeholder on a null or empty input so render sites can drop it
+// straight into a cell without a guard.
+
+export function formatFullDate(stamp: string | null | undefined): string {
+  if (!stamp) return "—";
+  const d = new Date(stamp);
+  const date = d.toLocaleDateString("en-PH", { month: "short", day: "numeric", year: "numeric" });
+  const time = d.toLocaleTimeString("en-PH", { hour: "numeric", minute: "2-digit", hour12: true });
+  return `${date} · ${time}`;
+}

package/src/utils/formatPHP.ts

@@ -0,0 +1,13 @@
+// Philippine peso currency formatter.
+//
+// Pure (.ts, no JSX): the single PHP-currency formatter every plugin had
+// copy-pasted as formatCurrency / formatPHP. Parses a string or number,
+// returns an em-dash placeholder on null / undefined / NaN, otherwise the
+// en-PH PHP-formatted string. Zero deps beyond the platform Intl global.
+
+export function formatPHP(amount: string | number | null | undefined): string {
+  if (amount === null || amount === undefined) return "—";
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (Number.isNaN(num)) return "—";
+  return new Intl.NumberFormat("en-PH", { style: "currency", currency: "PHP" }).format(num);
+}

package/src/utils/formatShortDate.ts

@@ -0,0 +1,17 @@
+// Short-date formatter for plugin remotes.
+//
+// Renders a YYYY-MM-DD (or full ISO) date string as the en-PH short form
+// (e.g. "Jan 5, 2026"). Hilinga is an Asia/Manila product, so the date part is
+// anchored at local midnight ("T00:00:00") to avoid the UTC drift that
+// toISOString would introduce. Returns an em-dash placeholder for a missing
+// value. Pure helper, no DOM, no fetch.
+
+export function formatShortDate(dateStr: string | null | undefined): string {
+  if (!dateStr) return "—";
+  const datePart = dateStr.includes("T") ? dateStr.split("T")[0] : dateStr;
+  return new Date(datePart + "T00:00:00").toLocaleDateString("en-PH", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}