@checkcourt/sdk 0.9.0 → 0.10.0

package/README.md

@@ -193,6 +193,36 @@ ui.form({
 });
 ```
 
+Blocks can carry an `icon` from `UI_ICONS` (text, heading, stat, badge, list items), a `stat`
+can be `size: "lg"`, badges have a soft amber `"warning"` variant, `ui.columns` lays out 2
+to 6 children in equal widths, and `ui.row(children, { justify: "between" })` spreads a row
+across the full width (first child left, last child right). A weather widget:
+
+```ts
+const days = [
+  ["Heute", "sun", "24°"],
+  ["Do", "cloud-sun", "21°"],
+  ["Fr", "cloud-rain", "17°"],
+  ["Sa", "cloud-drizzle", "18°"],
+  ["So", "sun", "23°"],
+] as const;
+
+ui.doc([
+  ui.row(
+    [
+      ui.stat("Jetzt", "24°", { icon: "sun", size: "lg", hint: "Sonnig" }),
+      ui.badge("Regen möglich", { variant: "warning", icon: "droplets" }),
+    ],
+    { justify: "between" },
+  ),
+  ui.divider(),
+  ui.columns(
+    days.map(([day, icon, temp]) => ui.stat(day, temp, { icon })),
+    { dividers: true, align: "center" },
+  ),
+]);
+```
+
 Compare `context.installation_id` and `context.tenant_id` with what you stored from
 `app.installed` before you act on a request. For the context token alone (for example in
 the backend of an iframe extension), use `verifyExtensionContext(token, secret)`.

package/dist/iframe.d.ts

@@ -6,7 +6,7 @@ export declare const MAX_TOAST_LENGTH = 200;
 /** Top-level areas `navigate()` may target; anything else is dropped by CheckCourt. */
 export declare const NAVIGABLE_SECTIONS: readonly ["dashboard", "booking", "my-bookings", "club", "team", "trainer", "fees", "arbeitsstunden", "settings", "admin"];
 /** CSS variables CheckCourt sends with every theme message. */
-export declare const THEME_TOKEN_NAMES: readonly ["--background", "--foreground", "--card", "--card-foreground", "--muted", "--muted-foreground", "--primary", "--primary-foreground", "--secondary", "--secondary-foreground", "--accent", "--accent-foreground", "--destructive", "--border", "--input", "--ring", "--radius"];
+export declare const THEME_TOKEN_NAMES: readonly ["--background", "--foreground", "--card", "--card-foreground", "--muted", "--muted-foreground", "--primary", "--primary-foreground", "--secondary", "--secondary-foreground", "--accent", "--accent-foreground", "--destructive", "--warning", "--warning-foreground", "--warning-muted", "--border", "--input", "--ring", "--radius"];
 export type ThemeTokenName = (typeof THEME_TOKEN_NAMES)[number];
 export type FrameMessage = {
     type: "checkcourt:resize";

package/dist/iframe.js

@@ -31,6 +31,9 @@ export const THEME_TOKEN_NAMES = [
     "--accent",
     "--accent-foreground",
     "--destructive",
+    "--warning",
+    "--warning-foreground",
+    "--warning-muted",
     "--border",
     "--input",
     "--ring",

package/dist/ui.d.ts

@@ -2,34 +2,55 @@ export declare const UI_VERSION = "v1";
 export declare const MAX_UI_BLOCKS = 50;
 /** Top-level blocks sit at depth 1; a container's children one deeper. */
 export declare const MAX_UI_DEPTH = 3;
-export declare const BADGE_VARIANTS: readonly ["default", "secondary", "outline", "destructive"];
+export declare const BADGE_VARIANTS: readonly ["default", "secondary", "outline", "destructive", "warning"];
 export declare const BUTTON_VARIANTS: readonly ["default", "secondary", "outline", "destructive"];
 export type BadgeVariant = (typeof BADGE_VARIANTS)[number];
 export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+/** Icons a block may show, by lucide name; CheckCourt draws them in the text color at text size. */
+export declare const UI_ICONS: readonly ["sun", "moon", "cloud", "cloud-sun", "cloud-moon", "cloud-sun-rain", "cloud-rain", "cloud-drizzle", "cloud-lightning", "cloud-snow", "cloud-fog", "snowflake", "wind", "droplet", "droplets", "umbrella", "thermometer", "sunrise", "sunset", "check", "x", "info", "alert-triangle", "triangle-alert", "alert-circle", "circle-alert", "clock", "calendar", "map-pin", "trophy", "users", "user", "lock", "unlock", "lock-open", "lightbulb", "zap", "euro", "star", "heart", "bell", "flag", "activity", "timer", "ticket", "door-open"];
+export type UiIcon = (typeof UI_ICONS)[number];
+/** `lg` shows the value as a large display figure, `md` (default) as a regular stat. */
+export declare const STAT_SIZES: readonly ["md", "lg"];
+export type StatSize = (typeof STAT_SIZES)[number];
+export declare const COLUMNS_ALIGNMENTS: readonly ["start", "center"];
+export type ColumnsAlignment = (typeof COLUMNS_ALIGNMENTS)[number];
+/** `between` spreads a row's children across the full width, first at the left edge, last at the right. */
+export declare const ROW_JUSTIFICATIONS: readonly ["start", "between"];
+export type RowJustify = (typeof ROW_JUSTIFICATIONS)[number];
+/** A `columns` block holds 2 to 6 children. */
+export declare const MIN_COLUMNS = 2;
+export declare const MAX_COLUMNS = 6;
 export type UiTextBlock = {
     type: "text";
     text: string;
     tone?: "muted";
+    icon?: UiIcon;
 };
 export type UiHeadingBlock = {
     type: "heading";
     text: string;
     level: 2 | 3;
+    icon?: UiIcon;
 };
+/** With `icon`, the icon sits before the value. */
 export type UiStatBlock = {
     type: "stat";
     label: string;
     value: string;
     hint?: string;
+    icon?: UiIcon;
+    size?: StatSize;
 };
 export type UiBadgeBlock = {
     type: "badge";
     label: string;
     variant?: BadgeVariant;
+    icon?: UiIcon;
 };
 export type UiListItem = {
     title: string;
     description?: string;
+    icon?: UiIcon;
 };
 export type UiListBlock = {
     type: "list";
@@ -136,8 +157,16 @@ export type UiStackBlock = {
 export type UiRowBlock = {
     type: "row";
     children: UiBlock[];
+    justify?: RowJustify;
 };
-export type UiBlock = UiTextBlock | UiHeadingBlock | UiStatBlock | UiBadgeBlock | UiListBlock | UiKeyValueBlock | UiLinkBlock | UiButtonBlock | UiFormBlock | UiDividerBlock | UiStackBlock | UiRowBlock;
+/** 2 to 6 children side by side in equal widths; on narrow cards 4 wrap to 2 per row, 5 and 6 to 3. */
+export type UiColumnsBlock = {
+    type: "columns";
+    children: UiBlock[];
+    dividers?: boolean;
+    align?: ColumnsAlignment;
+};
+export type UiBlock = UiTextBlock | UiHeadingBlock | UiStatBlock | UiBadgeBlock | UiListBlock | UiKeyValueBlock | UiLinkBlock | UiButtonBlock | UiFormBlock | UiDividerBlock | UiStackBlock | UiRowBlock | UiColumnsBlock;
 export type UiToast = {
     kind: "success" | "error";
     message: string;
@@ -265,12 +294,23 @@ export declare const ui: {
     readonly hidden: (options?: UiDocumentOptions) => UiHiddenDocument;
     readonly text: (text: string, options?: {
         tone?: "muted";
+        icon?: UiIcon;
     }) => UiTextBlock;
-    readonly heading: (text: string, level?: 2 | 3) => UiHeadingBlock;
+    /** `ui.heading(text, 3)` or `ui.heading(text, { level: 3, icon: "trophy" })`; level defaults to 2. */
+    readonly heading: (text: string, levelOrOptions?: 2 | 3 | {
+        level?: 2 | 3;
+        icon?: UiIcon;
+    }) => UiHeadingBlock;
     readonly stat: (label: string, value: string, options?: {
         hint?: string;
+        icon?: UiIcon;
+        size?: StatSize;
     }) => UiStatBlock;
-    readonly badge: (label: string, variant?: BadgeVariant) => UiBadgeBlock;
+    /** `ui.badge(label, "warning")` or `ui.badge(label, { variant: "warning", icon: "droplets" })`. */
+    readonly badge: (label: string, variantOrOptions?: BadgeVariant | {
+        variant?: BadgeVariant;
+        icon?: UiIcon;
+    }) => UiBadgeBlock;
     readonly list: (items: UiListItem[]) => UiListBlock;
     /** Pairs keep their order; a plain object is turned into pairs in key order. */
     readonly keyValue: (pairs: UiKeyValuePair[] | Record<string, string>) => UiKeyValueBlock;
@@ -294,8 +334,15 @@ export declare const ui: {
     };
     readonly divider: () => UiDividerBlock;
     readonly stack: (children: UiBlock[]) => UiStackBlock;
-    /** Horizontal, wraps on narrow screens. */
-    readonly row: (children: UiBlock[]) => UiRowBlock;
+    /** Horizontal, wraps on narrow screens; `justify: "between"` pushes the last child to the right edge. */
+    readonly row: (children: UiBlock[], options?: {
+        justify?: RowJustify;
+    }) => UiRowBlock;
+    /** 2 to 6 equal-width columns, optionally with vertical dividers; throws on any other count. */
+    readonly columns: (children: UiBlock[], options?: {
+        dividers?: boolean;
+        align?: ColumnsAlignment;
+    }) => UiColumnsBlock;
 };
 /** Toasts for `ui.doc(blocks, { toast })`, at most 200 characters. */
 export declare const toast: {

package/dist/ui.js

@@ -2,8 +2,65 @@ export const UI_VERSION = "v1";
 export const MAX_UI_BLOCKS = 50;
 /** Top-level blocks sit at depth 1; a container's children one deeper. */
 export const MAX_UI_DEPTH = 3;
-export const BADGE_VARIANTS = ["default", "secondary", "outline", "destructive"];
+export const BADGE_VARIANTS = ["default", "secondary", "outline", "destructive", "warning"];
 export const BUTTON_VARIANTS = ["default", "secondary", "outline", "destructive"];
+/** Icons a block may show, by lucide name; CheckCourt draws them in the text color at text size. */
+export const UI_ICONS = [
+    "sun",
+    "moon",
+    "cloud",
+    "cloud-sun",
+    "cloud-moon",
+    "cloud-sun-rain",
+    "cloud-rain",
+    "cloud-drizzle",
+    "cloud-lightning",
+    "cloud-snow",
+    "cloud-fog",
+    "snowflake",
+    "wind",
+    "droplet",
+    "droplets",
+    "umbrella",
+    "thermometer",
+    "sunrise",
+    "sunset",
+    "check",
+    "x",
+    "info",
+    "alert-triangle",
+    "triangle-alert",
+    "alert-circle",
+    "circle-alert",
+    "clock",
+    "calendar",
+    "map-pin",
+    "trophy",
+    "users",
+    "user",
+    "lock",
+    "unlock",
+    "lock-open",
+    "lightbulb",
+    "zap",
+    "euro",
+    "star",
+    "heart",
+    "bell",
+    "flag",
+    "activity",
+    "timer",
+    "ticket",
+    "door-open",
+];
+/** `lg` shows the value as a large display figure, `md` (default) as a regular stat. */
+export const STAT_SIZES = ["md", "lg"];
+export const COLUMNS_ALIGNMENTS = ["start", "center"];
+/** `between` spreads a row's children across the full width, first at the left edge, last at the right. */
+export const ROW_JUSTIFICATIONS = ["start", "between"];
+/** A `columns` block holds 2 to 6 children. */
+export const MIN_COLUMNS = 2;
+export const MAX_COLUMNS = 6;
 /** CheckCourt caps every render lifetime at this many seconds. */
 export const UI_CACHE_MAX_AGE_LIMIT = 300;
 /** Longest badge label of a `court.annotation`. */
@@ -75,6 +132,14 @@ function variantOf(variant, what) {
     }
     return variant;
 }
+function iconOf(icon) {
+    if (icon === undefined)
+        return undefined;
+    if (!UI_ICONS.includes(icon)) {
+        throw new TypeError(`Unknown icon ${String(icon)}; use one of UI_ICONS`);
+    }
+    return icon;
+}
 function entriesOf(list, what) {
     if (!Array.isArray(list))
         throw new TypeError(`${what} must be an array`);
@@ -157,19 +222,31 @@ export const ui = {
         return compact({ ui: UI_VERSION, hidden: true, toast: options.toast, cache: cacheOf(options.maxAge) });
     },
     text(text, options = {}) {
-        return compact({ type: "text", text, tone: options.tone });
+        return compact({ type: "text", text, tone: options.tone, icon: iconOf(options.icon) });
     },
-    heading(text, level = 2) {
-        return { type: "heading", text, level };
+    /** `ui.heading(text, 3)` or `ui.heading(text, { level: 3, icon: "trophy" })`; level defaults to 2. */
+    heading(text, levelOrOptions = 2) {
+        const options = typeof levelOrOptions === "object" ? levelOrOptions : { level: levelOrOptions };
+        return compact({ type: "heading", text, level: options.level ?? 2, icon: iconOf(options.icon) });
     },
     stat(label, value, options = {}) {
-        return compact({ type: "stat", label, value, hint: options.hint });
+        if (options.size !== undefined && !STAT_SIZES.includes(options.size)) {
+            throw new TypeError(`stat size must be one of ${STAT_SIZES.join(", ")}`);
+        }
+        return compact({ type: "stat", label, value, hint: options.hint, icon: iconOf(options.icon), size: options.size });
     },
-    badge(label, variant) {
-        return compact({ type: "badge", label, variant });
+    /** `ui.badge(label, "warning")` or `ui.badge(label, { variant: "warning", icon: "droplets" })`. */
+    badge(label, variantOrOptions) {
+        const options = typeof variantOrOptions === "object" ? variantOrOptions : { variant: variantOrOptions };
+        return compact({
+            type: "badge",
+            label,
+            variant: variantOf(options.variant, "badge variant"),
+            icon: iconOf(options.icon),
+        });
     },
     list(items) {
-        return { type: "list", items: items.map((item) => compact({ ...item })) };
+        return { type: "list", items: items.map((item) => compact({ ...item, icon: iconOf(item.icon) })) };
     },
     /** Pairs keep their order; a plain object is turned into pairs in key order. */
     keyValue(pairs) {
@@ -198,9 +275,22 @@ export const ui = {
     stack(children) {
         return { type: "stack", children };
     },
-    /** Horizontal, wraps on narrow screens. */
-    row(children) {
-        return { type: "row", children };
+    /** Horizontal, wraps on narrow screens; `justify: "between"` pushes the last child to the right edge. */
+    row(children, options = {}) {
+        if (options.justify !== undefined && !ROW_JUSTIFICATIONS.includes(options.justify)) {
+            throw new TypeError(`row justify must be one of ${ROW_JUSTIFICATIONS.join(", ")}`);
+        }
+        return compact({ type: "row", children, justify: options.justify });
+    },
+    /** 2 to 6 equal-width columns, optionally with vertical dividers; throws on any other count. */
+    columns(children, options = {}) {
+        if (!Array.isArray(children) || children.length < MIN_COLUMNS || children.length > MAX_COLUMNS) {
+            throw new RangeError(`columns takes ${MIN_COLUMNS} to ${MAX_COLUMNS} children`);
+        }
+        if (options.align !== undefined && !COLUMNS_ALIGNMENTS.includes(options.align)) {
+            throw new TypeError(`columns align must be one of ${COLUMNS_ALIGNMENTS.join(", ")}`);
+        }
+        return compact({ type: "columns", children, dividers: options.dividers, align: options.align });
     },
 };
 /** Toasts for `ui.doc(blocks, { toast })`, at most 200 characters. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkcourt/sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Official TypeScript SDK for the CheckCourt app platform",
   "private": false,
   "license": "MIT",