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
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;
No comments yet.