Official

ui

The look of the app's components: buttons, list rows, cards, settings, callouts, and the blocks and tables of replies. Edit a component here and the whole app draws with it.

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/ui@0.1.1

Permissions in 0.1.1

  • Change app settings settings.writeHighChanges the app settings.Apply the components' look to the window

Files

define.ts4 KB
// What a component is written with. A component is the props it reads,
// with their defaults, and a template: a JSX tree of `div`, `text`,
// `icon`, `spinner`, `canvas`, `slot` and other components, which the
// kernel expands for every instance where the view's tree is built
// (`plans/ui-components.md`). A template runs no code: it reads the
// instance's props through `prop()`, keeps or drops a node by `$if`, adds
// props by `$when` and repeats a node over a list by `$each`.
import { h } from "divergence";
import type { Child, Element } from "divergence";

/** The JSX factory of templates. A template's props are expressions the
 * kernel fills in per instance (`prop()`, theme paths such as
 * `"type.labelSize"`, `$if`, `$when`, `$each`), so its tags take any props;
 * the element props are checked where an instance is placed. Each template
 * module names it in the two JSX pragma comments at its top, the classic
 * runtime and this factory. (The pragmas are not quoted here: Bun reads one
 * in any comment, and a quoted one fails the build.) */
export function template(type: string, props: Readonly<Record<string, unknown>> | null, ...children: Child[]): Element {
  return h(type as "div", props, ...children);
}
export declare namespace template {
  namespace JSX {
    type Element = import("divergence").Element;
    interface IntrinsicElements {
      [tag: string]: Readonly<Record<string, unknown>>;
    }
  }
}

export interface Definition {
  /** The props the template reads, with their defaults (`null` for none).
   * Any other prop an instance is given (an `id`, `onClick`, a width)
   * lands on the template's root. */
  readonly props: Readonly<Record<string, unknown>>;
  readonly template: Element;
}

/** A condition: a prop that is set (`"icon"`), one that is not
 * (`"!label"`), any of several (`"icon|iconSvg"`), props equal to a value
 * or one of several (`{ variant: ["primary", "accent"] }`), or a list of
 * conditions that all hold. Besides props, `children` (the instance has
 * children), `slot.<name>` (it has that slot), `item.<field>` and `index`
 * (inside `$each`). */
export type Condition = string | Readonly<Record<string, unknown>> | readonly Condition[];

/** One entry of a node's `$when`: its props are merged in when `$if`
 * holds, a later entry over an earlier one, one level deep (a `hover`
 * merges with the `hover` before it). */
export type When = Readonly<{ $if: Condition } & Record<string, unknown>>;

/** The instance's prop at `path`, put in when the template is expanded;
 * the template's prop is left out when the instance has none and no
 * `else` is given. `map` translates values, `as: "percent"` writes 0.4 as
 * `"40%"`. */
export function prop(
  path: string,
  options: { map?: Readonly<Record<string, unknown>>; else?: unknown; as?: "percent" } = {},
): unknown {
  return { $: path, ...options };
}

export function when(condition: Condition, props: Readonly<Record<string, unknown>>): When {
  return { $if: condition, ...props };
}

/** cva-style variants: for each prop, the props each of its values adds,
 * as `$when` entries; `also` are conditions every entry needs besides
 * (`"!disabled"` for the hover of a button that can be pressed). */
export function variants(
  table: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, unknown>>>>>>,
  ...also: Condition[]
): When[] {
  return Object.entries(table).flatMap(([name, values]) =>
    Object.entries(values).map(([value, props]) =>
      when(also.length ? [{ [name]: value }, ...also] : { [name]: value }, props),
    ),
  );
}

/** The theme colour of each tone, for a tone prop that colours text. */
export const TONES = {
  foreground: "foreground",
  muted: "mutedForeground",
  faint: "faint",
  primary: "primary",
  info: "info",
  success: "success",
  warning: "warning",
  danger: "danger",
};

/** A child that takes the free width, and may shrink below its content. */
export const FILL = { flexGrow: 1, flexShrink: 1, flexBasis: "0%", minWidth: 0 } as const;

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.1.2latestNov 21, 2026>=5 <610.6 KB1 permissionListed
0.1.1Nov 16, 2026>=5 <610.2 KB1 permissionListed
0.1.0Nov 9, 2026>=5 <68.8 KB1 permissionListed

Reviews and comments

0 threads · 0 reviews

No comments yet.