@fraxic/ui 0.3.0 → 0.3.2

package/README.md

@@ -0,0 +1,344 @@
+# @fraxic/ui
+
+Build dashboard pages and handle dashboard interactions from a Fraxic application.
+
+Import from `@fraxic/ui` by package name:
+
+```ts
+import {
+  Chart,
+  ChartDataPoint,
+  ChartType,
+  ModalBuilder,
+  NoticeType,
+  SelectOption,
+  TextInputBuilder,
+  dashboard,
+  onButtonInteraction,
+  onModalInteraction,
+} from "@fraxic/ui";
+```
+
+## Dashboard Pages
+
+Register one `dashboard` handler. Fraxic calls it whenever the dashboard page renders.
+
+```ts
+dashboard((page) => {
+  page.section("Status", (section) => {
+    section.notice("Running", NoticeType.SUCCESS);
+    section.text("The application is healthy.");
+    section.progress("Queue", 3, 10);
+    section.button("Configure", "open-settings");
+  });
+});
+```
+
+`page.session` is a per-user session store. Use it for temporary UI state such as selected tabs, filters, and draft settings.
+
+```ts
+dashboard((page) => {
+  const tab = page.session.get<string>("tab") ?? "overview";
+
+  page.section("Controls", (section) => {
+    section.text(`Current tab: ${tab}`);
+    section.button("Overview", "tab:overview");
+    section.button("Settings", "tab:settings");
+  });
+});
+
+onButtonInteraction((interaction) => {
+  if (interaction.customId.startsWith("tab:")) {
+    interaction.session.set("tab", interaction.customId.slice("tab:".length));
+    interaction.reply("Updated.");
+  }
+});
+```
+
+## Layout
+
+Every page contains sections. Sections and containers can contain text, notices, progress bars, buttons, charts, tables, separators, and nested containers.
+
+```ts
+dashboard((page) => {
+  page.section("Overview", (section) => {
+    section.horizontal((row) => {
+      row.card((card) => {
+        card.text("Processed");
+        card.text("128");
+      });
+
+      row.card((card) => {
+        card.text("Errors");
+        card.notice("0", NoticeType.SUCCESS);
+      });
+    });
+
+    section.separator();
+
+    section.vertical((column) => {
+      column.text("Recent activity");
+      column.button("Refresh", "refresh");
+    });
+  });
+});
+```
+
+Container methods:
+
+- `horizontal(builder)` creates a horizontal child container.
+- `vertical(builder)` creates a vertical child container.
+- `card(builder)` creates a card child container.
+- `table(builder)` adds a table.
+- `text(content)` adds text.
+- `notice(message, type)` adds an info, warning, error, or success notice.
+- `progress(label, value, max)` adds a progress bar.
+- `separator()` adds a visual separator.
+- `button(label, customId)` adds a button.
+- `chart(chart)` adds a chart.
+
+## Tables
+
+Tables have optional header rows and body rows. Each row must have the same number of cells.
+
+```ts
+dashboard((page) => {
+  page.section("Jobs", (section) => {
+    section.table((table) => {
+      table.header((row) => {
+        row.cell((cell) => cell.text("Name"));
+        row.cell((cell) => cell.text("Status"));
+      });
+
+      table.row((row) => {
+        row.cell((cell) => cell.text("Sync"));
+        row.cell((cell) => cell.notice("Done", NoticeType.SUCCESS));
+      });
+    });
+  });
+});
+```
+
+## Charts
+
+Use `Chart`, `ChartType`, and `ChartDataPoint`.
+
+```ts
+dashboard((page) => {
+  page.section("Usage", (section) => {
+    section.chart(
+      new Chart(ChartType.LINE)
+        .label("Requests")
+        .data([
+          new ChartDataPoint("09:00", 12),
+          new ChartDataPoint("10:00", 19),
+          new ChartDataPoint("11:00", 17),
+        ])
+    );
+  });
+});
+```
+
+Chart types:
+
+- `ChartType.LINE`
+- `ChartType.BAR`
+- `ChartType.PIE`
+- `ChartType.AREA`
+
+## Buttons
+
+Register `onButtonInteraction` handlers for buttons.
+
+```ts
+onButtonInteraction((interaction) => {
+  if (interaction.customId === "refresh") {
+    interaction.reply("Refreshed.");
+  }
+});
+```
+
+Button interaction fields and methods:
+
+- `customId` is the button id.
+- `session` is the current user's `Session`.
+- `reply(message)` responds with a message.
+- `showModal(modal)` opens a modal.
+
+Each interaction can be replied to once.
+
+## Modals
+
+Use `ModalBuilder` to show forms from button interactions.
+
+```ts
+onButtonInteraction((interaction) => {
+  if (interaction.customId !== "open-settings") return;
+
+  interaction.showModal(
+    new ModalBuilder("settings", "Settings")
+      .addTextInput(
+        "Webhook URL",
+        new TextInputBuilder("webhookUrl")
+          .setPlaceholder("https://example.com/webhook")
+          .setRequired(true),
+        "Stored by the application."
+      )
+      .addColorInput("Accent color", new ColorInputBuilder("accent").setDefault("#3366FF"))
+  );
+});
+
+onModalInteraction((interaction) => {
+  if (interaction.customId !== "settings") return;
+
+  const webhookUrl = interaction.getTextInput("webhookUrl");
+  const accent = interaction.getColorInput("accent");
+
+  if (webhookUrl === null || !webhookUrl.startsWith("https://")) {
+    interaction.rejectInputs({ webhookUrl: "Enter an HTTPS URL." });
+    return;
+  }
+
+  interaction.session.set("settings", { webhookUrl, accent });
+  interaction.reply("Settings saved.");
+});
+```
+
+`ModalBuilder` methods:
+
+- `new ModalBuilder(customId, title)` creates a modal.
+- `addTextInput(label, input, description?)`
+- `addSelectInput(label, input, description?)`
+- `addFileInput(label, input, description?)`
+- `addColorInput(label, input, description?)`
+- `addDateInput(label, input, description?)`
+- `addParagraph(content, label?)`
+
+Modal interactions:
+
+- `getTextInput(customId)` returns `string | null`.
+- `getSelectInput(customId)` returns `string[]`.
+- `getFileInput(customId)` returns `Blob[]`.
+- `getDateInput(customId)` returns `Date | null`.
+- `getColorInput(customId)` returns `string | null`.
+- `reply(message)` closes the interaction with a success message.
+- `reject(message)` rejects the whole modal with a message.
+- `rejectInputs({ [customId]: message })` rejects specific inputs and keeps the modal open.
+
+## Inputs
+
+Text input:
+
+```ts
+new TextInputBuilder("name")
+  .setPlaceholder("Display name")
+  .setDefault("My app")
+  .setRequired(true)
+  .setMinLength(2)
+  .setMaxLength(80);
+```
+
+Use `.multiline()` for a multi-line text input.
+
+Select input:
+
+```ts
+new SelectInputBuilder("mode")
+  .setPlaceholder("Choose mode")
+  .addOption(new SelectOption("Fast", "fast"))
+  .addOption(new SelectOption("Careful", "careful").setSelected(true))
+  .setRequired(true)
+  .setMinValues(1)
+  .setMaxValues(1);
+```
+
+Searchable select input:
+
+```ts
+import { SelectInputBuilder, SelectOption, onSelectMenuSearch } from "@fraxic/ui";
+
+new SelectInputBuilder("user")
+  .setPlaceholder("Search users")
+  .setSearchable(true);
+
+onSelectMenuSearch((search) => {
+  if (search.customId !== "user") return;
+
+  const options = users
+    .filter((user) => user.name.toLowerCase().includes(search.query.toLowerCase()))
+    .slice(0, 25)
+    .map((user) => new SelectOption(user.name, user.id));
+
+  search.respond(options);
+});
+```
+
+File input:
+
+```ts
+new FileInputBuilder("attachments")
+  .setRequired(false)
+  .setMinFiles(0)
+  .setMaxFiles(3);
+```
+
+Date input:
+
+```ts
+new DateInputBuilder("runDate")
+  .setRequired(true)
+  .setDefault("2026-05-26");
+
+new DateInputBuilder("runAt")
+  .includeTime()
+  .setDefault(new Date());
+```
+
+Color input:
+
+```ts
+new ColorInputBuilder("accent")
+  .setRequired(false)
+  .setDefault("#3366FF");
+```
+
+## Session
+
+`Session` stores temporary per-user dashboard state.
+
+```ts
+const count = interaction.session.get<number>("count") ?? 0;
+interaction.session.set("count", count + 1);
+interaction.session.update<number>("count", (current) => (current ?? 0) + 1);
+interaction.session.delete("count");
+interaction.session.clear();
+```
+
+Session methods:
+
+- `get<T>(key)` returns `T | null`.
+- `set<T>(key, value)` stores a value; `null` removes the key.
+- `update<T>(key, updater)` updates a value.
+- `delete(key)` removes a value and returns whether it existed.
+- `list()` returns stored keys.
+- `clear()` removes all session values.
+
+Use application files or a database such as SQLite for durable state. Session values are for UI state only.
+
+## Validation And Limits
+
+Inputs validate before `onModalInteraction` runs. If validation fails, the modal is shown again with input errors.
+
+Important limits:
+
+- Text values are limited to 5000 characters.
+- `customId` is limited to 100 characters.
+- A page can contain up to 200 components.
+- UI nesting depth is limited to 8.
+- A table can contain up to 100 rows and 20 cells per row.
+- A chart can contain up to 200 points.
+- A modal can contain up to 10 components.
+- A select input can contain up to 100 options.
+- A file input accepts files up to 5 MiB each.
+
+Use stable `customId` values. Prefix ids when there are multiple features, for example `settings:save` or `job:retry:123`.

package/index.d.ts

@@ -164,4 +164,3 @@ export declare function dashboard(handler: (page: Page) => void): void;
 export declare function onButtonInteraction(handler: (interaction: ButtonInteraction) => void): void;
 export declare function onModalInteraction(handler: (interaction: ModalInteraction) => void): void;
 export declare function onSelectMenuSearch(handler: (search: SelectMenuSearch) => void): void;
-export declare function __fraxicHandleUiRequest(payload: unknown): unknown;

package/index.js

@@ -18,6 +18,8 @@ const modalHandlers = [];
 const selectMenuSearchHandlers = [];
 const sessions = new Map();
 const modalSchemas = new Map();
+let ipcRegistered = false;
+let ipcRegistrationQueued = false;
 
 function requireText(name, value) {
   if (typeof value !== "string") throw new Error(`${name} must be a string`);
@@ -894,21 +896,25 @@ export class SelectMenuSearch {
 
 export function dashboard(handler) {
   dashboardHandler = handler;
+  ensureIpcRegistered();
 }
 
 export function onButtonInteraction(handler) {
   buttonHandlers.push(handler);
+  ensureIpcRegistered();
 }
 
 export function onModalInteraction(handler) {
   modalHandlers.push(handler);
+  ensureIpcRegistered();
 }
 
 export function onSelectMenuSearch(handler) {
   selectMenuSearchHandlers.push(handler);
+  ensureIpcRegistered();
 }
 
-export function __fraxicHandleUiRequest(payload) {
+function handleUiRequest(payload) {
   const request = payload;
   if (request.type === "render") return render(request);
   if (request.type === "button") return handleButton(request);
@@ -984,8 +990,19 @@ function noResponse() {
   return { ok: false, reason: "noResponse" };
 }
 
+function ensureIpcRegistered() {
+  if (ipcRegistered || ipcRegistrationQueued) return;
+  ipcRegistrationQueued = true;
+  queueMicrotask(() => {
+    ipcRegistrationQueued = false;
+    if (ipcRegistered) return;
+    const listen = globalThis.__fraxic?.ipc?.listen;
+    if (typeof listen !== "function") return;
+    listen("ui", handleUiRequest);
+    ipcRegistered = true;
+  });
+}
+
 function ensureModalHasComponents(modal) {
   if (modal.toMap().components.length === 0) throw new Error("modal must have at least 1 component");
 }
-
-globalThis.__fraxic?.ipc?.listen?.("ui", __fraxicHandleUiRequest);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@fraxic/ui",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
     "index.js",
-    "index.d.ts"
+    "index.d.ts",
+    "README.md"
   ],
   "exports": {
     ".": {