@kahitsan/ksui 0.3.0 → 0.5.0

package/README.md

@@ -1,45 +1,140 @@
 # @kahitsan/ksui
 
-The single canonical copy of the shared SolidJS UI components that KahitSan/Hilinga
-plugins consume — pickers, the mention textarea, markdown notes, the camera +
-attachment tiles, and the data-driven account avatar — plus the `@kserp/host-ui`
-ambient type contract for the host UI kit.
+[![npm version](https://img.shields.io/npm/v/@kahitsan/ksui.svg)](https://www.npmjs.com/package/@kahitsan/ksui)
+[![npm downloads](https://img.shields.io/npm/dm/@kahitsan/ksui.svg)](https://www.npmjs.com/package/@kahitsan/ksui)
+[![license](https://img.shields.io/npm/l/@kahitsan/ksui.svg)](./LICENSE)
 
-Extracted from `kserp/packages/plugin-ui` (`@kahitsan/plugin-ui`) into its own repo
-so the UI package versions and publishes independently of the kernel.
+A set of UI components for SolidJS apps, built and used by the KahitSan team.
+
+On npm: [@kahitsan/ksui](https://www.npmjs.com/package/@kahitsan/ksui). Docs:
+[ksui.kahitsan.com](https://ksui.kahitsan.com/).
+
+## What this is
+
+`@kahitsan/ksui` is a small library of ready-made user interface pieces for
+[SolidJS](https://www.solidjs.com/). SolidJS is a way to build web pages with
+reusable components, a bit like React but with its own way of working. These
+components are written for SolidJS only. They will not work in React or Vue.
+
+Inside you will find small building-block components, ready-made widgets built
+from them, and a few non-visual helpers. The full, always-current list lives in
+the docs (see below), so this README stays short on purpose.
+
+## Where you can use it
+
+There are two ways to use KSUI.
+
+1. **In your own SolidJS project.** Install it from npm and use the components
+   like any other dependency. It is MIT licensed, so you are free to use it in
+   personal or commercial work. See the License section below.
+2. **As a contributor to KahitSan plugins.** If you build or help with our
+   plugins, these are the shared components you reuse instead of writing your
+   own copy.
+
+One honest note so nothing surprises you. Some components are self-contained and
+work right away. Others, like the client, voucher, and payment account pickers,
+expect a backend that answers certain requests, so they fit best inside an app
+built the KahitSan way. A few components also expect a small set of shared UI
+pieces from your app, like a button and a dialog. The setup note below explains
+that part, and each component page says what it needs.
+
+## What is inside
+
+The package is organized into three kinds of exports:
+
+- **Base components** are the small building blocks, like form fields, status
+  pills, tooltips, progress bars, and avatars.
+- **Composite components** combine those building blocks into ready-made widgets,
+  like the search-and-pick selectors and the notes editor.
+- **Utils** are non-visual helpers, like the peso and date formatters and the
+  safe link builders.
+
+We do not list every component here on purpose, so this README does not fall out
+of date as the set grows. The complete, current catalog, with a live example and
+the props for each one, is in the docs:
+
+**https://ksui.kahitsan.com/**
 
 ## Install
 
-Published to the **public npm registry** (npmjs.com) as `@kahitsan/ksui` — no
-registry config or auth needed:
+`@kahitsan/ksui` is on the public npm registry, so no extra registry setup or
+login is needed.
 
 ```
 npm install @kahitsan/ksui
 ```
 
-## How it ships
+You also need a SolidJS app. If you are starting fresh, set one up with
+[`vite-plugin-solid`](https://github.com/solidjs/vite-plugin-solid), which is the
+tool that compiles Solid components.
 
-This is a SolidJS component library shipped as **source** under a `solid` export
-condition (see `package.json`). The consumer's `vite-plugin-solid` compiles the
-components, while `solid-js` and `@kserp/host-ui` stay **externalized** to the host
-runtime globals — so the component source is bundled into the plugin IIFE exactly
-as a local copy would be: one Solid instance, the host UI kit reused. `lucide-solid`
-is bundled from the consumer's own deps.
+## A tiny usage example
 
-Consumers must keep `solid-js` + `@kserp/host-ui` externalized in their
-`vite.remote.config.ts`, and (until a `.d.ts` bundle ships) reference the host kit
-types via the `./host-ui` export:
+```tsx
+import { createSignal } from "solid-js";
+import { MentionTextarea } from "@kahitsan/ksui";
 
-```ts
-/// <reference types="@kahitsan/ksui/host-ui" />
+function NotesField() {
+  const [value, setValue] = createSignal("");
+  return (
+    <MentionTextarea
+      value={value()}
+      setValue={setValue}
+      placeholder="Add notes, type @ to tag a client"
+      rows={3}
+    />
+  );
+}
 ```
 
-## Type-checking
+The avatar chip is also easy and needs no backend:
+
+```tsx
+import { AccountAvatar } from "@kahitsan/ksui";
+
+<AccountAvatar account={{ id: 0, type: "user", name: "Maria Cruz" }} size={32} />;
+```
+
+## The honest setup note
+
+Two things this library expects from the app around it:
+
+1. **`solid-js` stays external.** This library ships as source, and your own
+   `vite-plugin-solid` compiles it. Keep `solid-js` as a single shared copy in
+   your app (not bundled twice), so there is only one Solid instance running.
+
+2. **A host UI kit under the name `@kserp/host-ui`.** Some components import
+   shared pieces from your app, like a `Button`, a `confirm` dialog, and a few
+   hooks. Your app provides these under the import name `@kserp/host-ui`, and that
+   name is kept external at build time too. Components that need it are:
+   MarkdownNotes, ClientPicker, CameraCapture, ExistingAttachmentTile, and the
+   `useAccountsIndex` hook. The rest do not need it.
+
+So a few components work right away with no backend and no host kit
+(MentionTextarea as a plain notes box, AccountAvatar, AddAttachmentTile,
+VoucherPicker, and all the helper functions). Others assume the ERP host and a
+backend that answers calls like `/api/clients`. The docs site walks through how
+to mock the host kit and stub those calls so you can see every component render.
+
+## Docs
+
+The full documentation site, with a component-by-component guide and setup steps,
+will be at:
+
+https://ksui.kahitsan.com/
+
+## Contributing
+
+We welcome help. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for how to set
+up the repo, the code style we follow, and how to send a change.
+
+## License
 
-`npm run typecheck` runs `tsc --noEmit` standalone (`jsxImportSource: solid-js`, the
-shipped `host-ui.d.ts` in scope). The authoritative gate remains each consuming
-plugin's own `tsc`, where the plugin's `lucide-solid` and host runtime are present.
+MIT. See [LICENSE](./LICENSE). You are free to use KSUI in your own personal or
+commercial SolidJS projects, as long as you keep the MIT license notice. Source
+lives at https://github.com/KahitSan/ksui.
 
-## Publishing
+---
 
-Push a `v*` tag (e.g. `v0.3.0`); the release workflow publishes to GitHub Packages.
+Created with ♥ by [Luis Edward Miranda](https://github.com/llupRisinglll) for
+KahitSan Corp.

package/host-ui.d.ts

@@ -1,12 +1,12 @@
 // CANONICAL SDK type defs for the host UI kit (window.__KSERP_UI__, externalized
-// as "@kserp/host-ui"). This ships in @kahitsan/plugin-ui and is the single
-// source of truth — every plugin (ours, and any third-party with no kernel
+// as "@kserp/host-ui"). This ships in @kahitsan/ksui and is the single
+// source of truth. Every plugin (ours, and any third-party with no kernel
 // source) gets it from the installed package via
-// `/// <reference types="@kahitsan/plugin-ui/host-ui" />`; there are no more
+// `/// <reference types="@kahitsan/ksui/host-ui" />`; there are no more
 // per-plugin copies to drift. The host owns the runtime: its remote loader
 // (kserp src/lib/remote-loader.ts) populates the global from the host's kit
 // barrel (kserp src/lib/host-ui.tsx) before loading any remote. Keep this in sync
-// with that barrel — every member here must be exported there, and vice-versa.
+// with that barrel. Every member here must be exported there, and vice versa.
 declare module "@kserp/host-ui" {
   import type { JSX, Accessor } from "solid-js";
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.3.0",
-  "description": "ksui — shared SolidJS UI components + the @kserp/host-ui type contract for KahitSan/Hilinga plugins. Published to GitHub Packages and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with solid-js + @kserp/host-ui externalized to the host runtime.",
+  "version": "0.5.0",
+  "description": "ksui is a set of shared SolidJS UI components plus the @kserp/host-ui type contract for KahitSan/Hilinga plugins. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with solid-js + @kserp/host-ui externalized to the host runtime.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -21,7 +21,10 @@
     "host-ui.d.ts"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
   },
   "dependencies": {
     "lucide-solid": "^1.7.0"
@@ -30,6 +33,7 @@
     "solid-js": "^1.9.0"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "solid-js": "^1.9.0",
     "typescript": "^5.6.0"
   },

package/src/components/{AccountAvatar.tsx → base/AccountAvatar.tsx}

@@ -1,15 +1,15 @@
-// AccountAvatar — renders a small visual chip for an account or a user.
+// AccountAvatar renders a small visual chip for an account or a user.
 //
 // Two distinct semantics share this chip, and the chip picks by intent:
 //
-//   • ACCOUNT (a financial account — the default). Shows the account's
+//   • ACCOUNT (a financial account, the default). Shows the account's
 //     uploaded logo, else its chosen icon glyph (the slug picked in the
 //     financial-accounts create/edit modal, or the type default). NEVER an
 //     initials circle, and the container is a ROUNDED SQUARE (rounded-md).
-//     This matches the /financial-accounts page exactly — a financial
+//     This matches the /financial-accounts page exactly. A financial
 //     account is not a person, so it must not render as an initials avatar.
 //
-//   • USER (a person badge — calendar entries, mention lists, timesheet
+//   • USER (a person badge for calendar entries, mention lists, timesheet
 //     attribution). Shows the profile photo, else an initial-on-color
 //     CIRCLE, in a circular (rounded-full) container. Callers opt in with
 //     `{ id: 0, type: 'user', name: 'Myra Abilay', image }` (the `type:
@@ -21,10 +21,10 @@
 
 import { Show } from "solid-js";
 import { Dynamic } from "solid-js/web";
-import { getAccountIcon } from "../lib/account-icons";
-import { buildLogoSrc } from "../lib/account-logo-url";
+import { getAccountIcon } from "../../utils/account-icons";
+import { buildLogoSrc } from "../../utils/account-logo-url";
 
-// Shared 16-color palette and initials algorithm — keep in lockstep with
+// Shared 16-color palette and initials algorithm. Keep in lockstep with
 // the kserp's ~/lib/avatar.ts so the host runtime and the plugin fleet
 // render the same chip for the same user.  Exported so any future widget
 // (or a caller's inline use) can derive a user's color/initials without
@@ -52,7 +52,7 @@ export function getAvatarColor(name: string): string {
 
 /** Build a base64 SVG data URL for the initial-on-color circle.  Because it
  *  renders as an `<img>`, the chip scales uniformly with every other source
- *  (photo, s3 logo) — no per-plugin/inline text-size drift.  The viewBox is
+ *  (photo, s3 logo), so there is no per-plugin/inline text-size drift.  The viewBox is
  *  100×100 and the font-size is calculated to keep 2-character initials
  *  comfortably inside the circle. */
 export function buildInitialsSvg(name: string): string {
@@ -81,7 +81,7 @@ export interface AvatarAccount {
    *  account variant, which never renders initials. */
   name?: string;
   /** User profile photo URL (e.g. Google identity provider). USER variant
-   *  only — higher priority than the initials fallback. */
+   *  only. Higher priority than the initials fallback. */
   image?: string | null;
 }
 
@@ -136,7 +136,7 @@ export default function AccountAvatar(props: AccountAvatarProps) {
         when={isUser()}
         fallback={
           // ACCOUNT: uploaded logo (rounded square), else the chosen icon
-          // glyph. No initials — a financial account is not a person.
+          // glyph. No initials, since a financial account is not a person.
           <Show when={props.account.s3_link} fallback={iconGlyph()}>
             <img
               src={buildLogoSrc(props.account.s3_link)}

package/src/components/base/ChartLegend.tsx

@@ -0,0 +1,34 @@
+// ChartLegend renders a single legend entry for a chart: a small colored dot,
+// an uppercase label, and a value beneath it. Used by cashflow / analytics
+// charts to label each series (money in, money out, net) with its current
+// total. Purely presentational; the caller supplies the dot color class, the
+// label, the formatted value, and an optional value color override.
+
+interface ChartLegendProps {
+  /** Tailwind background class for the legend dot (e.g. "bg-emerald-400"). */
+  dot: string;
+  /** Uppercase label shown above the value (e.g. "Money in"). */
+  label: string;
+  /** Pre-formatted value string (e.g. a currency string). */
+  value: string;
+  /** Optional Tailwind text color class for the value. Defaults to text-zinc-100. */
+  valueColor?: string;
+}
+
+export default function ChartLegend(props: ChartLegendProps) {
+  return (
+    <div class="flex items-center gap-2">
+      <span class={`w-2 h-2 rounded-sm ${props.dot}`} />
+      <div class="flex flex-col">
+        <span class="text-[9px] uppercase tracking-widest text-zinc-500 font-medium leading-tight">
+          {props.label}
+        </span>
+        <span
+          class={`text-xs font-bold tabular-nums leading-tight ${props.valueColor || "text-zinc-100"}`}
+        >
+          {props.value}
+        </span>
+      </div>
+    </div>
+  );
+}

package/src/components/base/CopyButton.tsx

@@ -0,0 +1,53 @@
+import { createSignal, onCleanup, type JSX } from "solid-js";
+import Copy from "lucide-solid/icons/copy";
+import Check from "lucide-solid/icons/check";
+
+interface CopyButtonProps {
+  /** The text written to the clipboard on click. Caller owns the value. */
+  text: string;
+  /** Label shown in the default state. Default "Copy". */
+  label?: string;
+  /** Label shown for ~1.5s after a successful copy. Default "Copied". */
+  copiedLabel?: string;
+  /** Accessible label for the button. Default "Copy". */
+  ariaLabel?: string;
+  /** Icon size in px. Default 12. */
+  size?: number;
+  /** Extra classes on the button. */
+  class?: string;
+}
+
+// Self-contained copy-to-clipboard button. Owns its own "copied" signal:
+// on click it writes props.text via navigator.clipboard, flips copied true
+// for ~1500ms, swaps the label, and shows the lucide Check icon while copied
+// (Copy icon otherwise). The pending timer is cleared on cleanup so a copy
+// flash never fires after the button unmounts. No domain coupling — the
+// caller passes the text and any label overrides.
+export default function CopyButton(props: CopyButtonProps): JSX.Element {
+  const [copied, setCopied] = createSignal(false);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const handleClick = () => {
+    navigator.clipboard.writeText(props.text).then(() => {
+      setCopied(true);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => setCopied(false), 1500);
+    });
+  };
+
+  onCleanup(() => {
+    if (timer) clearTimeout(timer);
+  });
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      aria-label={props.ariaLabel ?? "Copy"}
+      class={`ks-interactive px-2 py-1.5 rounded bg-zinc-800 border border-zinc-700 text-zinc-300 hover:text-white text-xs flex items-center gap-1 ${props.class ?? ""}`}
+    >
+      {copied() ? <Check size={props.size ?? 12} /> : <Copy size={props.size ?? 12} />}
+      {copied() ? (props.copiedLabel ?? "Copied") : (props.label ?? "Copy")}
+    </button>
+  );
+}

package/src/components/base/DateTile.tsx

@@ -0,0 +1,84 @@
+// DateTile — a compact calendar day cell.
+//
+// A 60x68 tile with three stacked parts: a small top band (e.g. a month
+// label), a big primary value (e.g. the day-of-month), and an optional
+// muted sub-label (e.g. hours worked, a count, a short note). It is the
+// visual unit a caller repeats into a ledger-style row of days — scanned
+// like a register, not rendered as a full month grid.
+//
+// Domain-free by design: it knows nothing about timesheets, payroll, or any
+// data shape. The caller formats every string it shows (`topLabel`,
+// `value`, `subLabel`) and owns selection state. Pass `onToggle` to make the
+// tile an interactive, selectable button (with `aria-pressed`); omit it for a
+// static, read-only cell that renders dimmed so a row can show which tiles are
+// "in" vs "out" of a selection at a glance.
+
+import { Show, type JSX } from "solid-js";
+import { Dynamic } from "solid-js/web";
+
+export interface DateTileProps {
+  /** The big primary value — typically a day-of-month number, but any short
+   *  string works (the caller formats it). */
+  value: number | string;
+  /** Small uppercase band above the value, e.g. a month label ("MAY"). */
+  topLabel?: string;
+  /** Muted line below the value, e.g. "10h" or a short count. */
+  subLabel?: string;
+  /** Selected state. For interactive tiles this drives the amber accent +
+   *  `aria-pressed`; ignored for read-only tiles (they always render "on"). */
+  selected?: boolean;
+  /** Make the tile a selectable button. When omitted the tile is a static,
+   *  non-interactive cell. */
+  onToggle?: () => void;
+  /** Optional test id, applied only to interactive tiles. */
+  testId?: string;
+}
+
+export default function DateTile(props: DateTileProps): JSX.Element {
+  const interactive = (): boolean => !!props.onToggle;
+  const on = (): boolean => (interactive() ? props.selected ?? false : true);
+  return (
+    <Dynamic
+      component={interactive() ? "button" : "div"}
+      type={interactive() ? "button" : undefined}
+      onClick={props.onToggle}
+      aria-pressed={interactive() ? on() : undefined}
+      data-testid={interactive() ? props.testId : undefined}
+      style={{ width: "60px", height: "68px", flex: "0 0 auto" }}
+      class={`${interactive() ? "cursor-pointer" : ""} flex flex-col rounded-md overflow-hidden border transition-colors`}
+      classList={{
+        "border-amber-500/25 bg-zinc-800/40": on(),
+        "border-zinc-800/60 bg-zinc-900/40 opacity-50 hover:opacity-80": !on(),
+      }}
+    >
+      <div
+        style={{ height: "18px" }}
+        class="flex items-center justify-center text-[9px] font-semibold uppercase tracking-[0.15em] bg-zinc-800/70 text-zinc-500"
+      >
+        {props.topLabel ?? ""}
+      </div>
+      <div class="flex-1 flex flex-col items-center justify-center">
+        <div
+          class="text-xl font-semibold leading-none tabular-nums"
+          classList={{
+            "text-amber-400/90": on(),
+            "text-zinc-500": !on(),
+          }}
+        >
+          {props.value}
+        </div>
+        <Show when={props.subLabel != null && props.subLabel !== ""}>
+          <div
+            class="text-[9px] mt-0.5 tabular-nums"
+            classList={{
+              "text-zinc-500": on(),
+              "text-zinc-700": !on(),
+            }}
+          >
+            {props.subLabel}
+          </div>
+        </Show>
+      </div>
+    </Dynamic>
+  );
+}

package/src/components/base/DetailRow.tsx

@@ -0,0 +1,17 @@
+// DetailRow renders a single labeled read-only field: a small muted label
+// stacked above its value, with an em-dash placeholder when the value is
+// empty. Used in detail/view surfaces (e.g. the client detail modal) to lay
+// out a record's fields uniformly.
+//
+// Ported verbatim from kplugin_clients/ui/remote/index.tsx. It is purely
+// presentational with no external dependencies, so the only adaptation is
+// the move into the shared kit.
+
+export default function DetailRow(props: { label: string; value: string | null | undefined }) {
+  return (
+    <div>
+      <span class="text-xs text-zinc-500 block">{props.label}</span>
+      <span class="text-sm text-zinc-200">{props.value || "—"}</span>
+    </div>
+  );
+}

package/src/components/{ExistingAttachmentTile.tsx → base/ExistingAttachmentTile.tsx}

@@ -9,7 +9,7 @@ import Paperclip from "lucide-solid/icons/paperclip";
 import X from "lucide-solid/icons/x";
 import TriangleAlert from "lucide-solid/icons/triangle-alert";
 import { confirm } from "@kserp/host-ui";
-import { attachmentUrl, isResolvableAttachment } from "../lib/attachments";
+import { attachmentUrl, isResolvableAttachment } from "../../utils/attachments";
 
 export interface ExistingAttachment {
   id: number;
@@ -39,7 +39,7 @@ export default function ExistingAttachmentTile(props: Props) {
         fallback={
           <div
             class="flex w-24 h-24 flex-col items-center justify-center gap-1 rounded-lg border border-dashed border-zinc-700 bg-zinc-900/40 px-2 text-center text-zinc-500"
-            title={`${props.attachment.file_name} — file is no longer available`}
+            title={`${props.attachment.file_name} (file is no longer available)`}
           >
             <TriangleAlert size={18} class="text-amber-500/70" />
             <span class="truncate max-w-full text-[10px]">{props.attachment.file_name}</span>

package/src/components/base/FormErrorBanner.tsx

@@ -0,0 +1,27 @@
+import { Show, type JSX } from "solid-js";
+
+interface FormErrorBannerProps {
+  /** The error message to display. When falsy (null / undefined / empty
+   *  string) the banner renders nothing, so callers do not need to wrap
+   *  it in their own <Show>. */
+  message: string | null | undefined;
+  /** Extra classes on the banner. Use this for margin spacing such as
+   *  "mt-3" or "mb-3" — the banner ships no margin of its own. */
+  class?: string;
+}
+
+// Standard form error banner: the red role="alert" box that nearly every
+// create/edit modal hand-rolls. Self-guarding — it renders nothing when the
+// message is falsy, so a surrounding <Show> is unnecessary.
+export default function FormErrorBanner(props: FormErrorBannerProps): JSX.Element {
+  return (
+    <Show when={props.message}>
+      <div
+        role="alert"
+        class={`rounded-md border border-red-500/30 bg-red-500/10 px-3 py-2 text-xs text-red-300 ${props.class ?? ""}`}
+      >
+        {props.message}
+      </div>
+    </Show>
+  );
+}

package/src/components/base/FormField.tsx

@@ -0,0 +1,19 @@
+// FormField is a small presentational wrapper for a labeled form control. It
+// renders a label above the control, the control itself (passed as children),
+// and an optional hint line below. Copied faithfully from the packages plugin
+// remote UI atoms; behavior is unchanged.
+
+import { Show } from "solid-js";
+import type { JSX } from "solid-js";
+
+export default function FormField(props: { label: string; children: JSX.Element; hint?: string }) {
+  return (
+    <div>
+      <label class="block text-xs text-zinc-500 mb-1">{props.label}</label>
+      {props.children}
+      <Show when={props.hint}>
+        <p class="text-[10px] text-zinc-600 mt-1">{props.hint}</p>
+      </Show>
+    </div>
+  );
+}