@kahitsan/ksui 0.3.0 → 0.4.0

package/README.md

@@ -1,45 +1,128 @@
 # @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.
+A set of UI components for SolidJS apps, built and used by the KahitSan team.
 
-Extracted from `kserp/packages/plugin-ui` (`@kahitsan/plugin-ui`) into its own repo
-so the UI package versions and publishes independently of the kernel.
+## 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://kahitsan.github.io/ksui/**
 
 ## 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://kahitsan.github.io/ksui/
+
+## Contributing
 
-`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.
+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.
 
-## Publishing
+## License
 
-Push a `v*` tag (e.g. `v0.3.0`); the release workflow publishes to GitHub Packages.
+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.

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.4.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/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>
+  );
+}