@domicile-desktop/sdk 0.0.0-alpha-e77cfff77793 → 0.0.0-alpha-5166c4cfb4be

package/README.md

@@ -63,6 +63,7 @@ See [docs/ELEMENTS.md](docs/ELEMENTS.md) for `<app>` input and focus, and the
 | `./system` | `system(domicile)`: files, watches, processes and D-Bus. Calls resolve a `Result`; the compositor refuses most while the desktop is locked. See [SHELL-SYSTEM-ACCESS.md](/docs/SHELL-SYSTEM-ACCESS.md). |
 | `./portal` | `watchPortalRequests` and `answerPortalRequest`: application dialogs from `xdg-desktop-portal`, parsed by kind. `watchCapturing` and `stopCapturing`: running sessions that record the screen or control or capture input. `<PortalDialogs />` in component-library draws them. See [PORTALS.md](/docs/PORTALS.md). |
 | `./global-shortcuts` | `fireGlobalShortcuts`: grab the chords applications hold through the GlobalShortcuts portal and report each press and release. `<PortalDialogs />` calls it. |
+| `./options` | `defineOptions` and `option`: the options a shell declares as its `options` export, which the Settings app edits. `watchShellOptions` reads the config's values of them, live. See [WRITING-A-SHELL.md](/docs/WRITING-A-SHELL.md#options). |
 | `./appearance` | `watchAppearance`: the config's accent color, contrast and reduced motion, which the Settings portal also serves applications. See [SHELL-CONFIG.md](/docs/SHELL-CONFIG.md#theme). |
 | `./icon-theme` | `readIconTheme(system)`: the config's `theme.icon_theme`, read from the compositor's Settings portal, or `None` for `hicolor` only. `watchIconTheme` reads it and follows `SettingChanged`. `@domicile-desktop/system-apps/app-icons` takes it. |
 | `./extension`, `./tray`, `./notification`, `./theme`, `./display-transform` | Data types and Zod schemas for what the desktop holds. |

package/config.schema.json

@@ -503,6 +503,12 @@
       "description": "The shell `domicile` runs when given none: a path or a package, as\n`domicile load-shell` takes. The compositor ignores it.",
       "type": ["string", "null"]
     },
+    "shell_options": {
+      "additionalProperties": true,
+      "default": {},
+      "description": "The values of the options the shell declares, by key. The compositor\nsends them to the shell without reading them. See\n`docs/WRITING-A-SHELL.md#options`.",
+      "type": "object"
+    },
     "startup": {
       "$ref": "#/$defs/StartupConfig"
     },

package/dist/config.d.ts

@@ -14,6 +14,12 @@ export type Config = {
      * `domicile load-shell` takes. The compositor ignores it.
      */
     shell?: string | null;
+    /**
+     * The values of the options the shell declares, by key. The compositor
+     * sends them to the shell without reading them. See
+     * `docs/WRITING-A-SHELL.md#options`.
+     */
+    shell_options?: Record<string, unknown>;
     startup?: StartupConfig;
     theme?: ThemeConfig;
 };

package/dist/domicile-host.d.ts

@@ -317,6 +317,7 @@ export type DomicileHostEventMap = {
     windowsthemechanged: Event;
     modifierschanged: Event;
     appearancechanged: Event;
+    shelloptionschanged: Event;
     /**
      * Fires when a window opens, closes, navigates or changes title. Read
      * `browserWindows` for the current list.
@@ -638,6 +639,13 @@ export type DomicileHost = {
     readonly accentColor: string | null;
     readonly highContrast: boolean | null;
     readonly reducedMotion: boolean | null;
+    /**
+     * The config's `shell_options` as JSON text: the values of the options the
+     * shell declares. Null until the compositor says. Text rather than an
+     * object, so the page parses it against its own declaration; see the SDK's
+     * `watchShellOptions`.
+     */
+    readonly shellOptions: string | null;
     /**
      * The desk's browser windows, oldest first. Null until the browser lists
      * them, which it does as soon as this page listens. The browser holds each

package/dist/fake-host.js

@@ -24,6 +24,7 @@ const CHANGED = {
     metaKey: "modifierschanged",
     notifications: "notificationschanged",
     reducedMotion: "appearancechanged",
+    shellOptions: "shelloptionschanged",
     shiftKey: "modifierschanged",
     theme: "themechanged",
     tray: "traychanged",
@@ -46,6 +47,7 @@ const UNDESCRIBED = {
     metaKey: null,
     notifications: null,
     reducedMotion: null,
+    shellOptions: null,
     shiftKey: null,
     theme: null,
     tray: null,

package/dist/options.d.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import type { DomicileHost } from "./domicile-host";
+declare const toggleSchema: z.ZodObject<{
+    default: z.ZodBoolean;
+    kind: z.ZodLiteral<"toggle">;
+    label: z.ZodString;
+}, z.core.$strict>;
+declare const choiceSchema: z.ZodObject<{
+    choices: z.ZodArray<z.ZodString>;
+    default: z.ZodString;
+    kind: z.ZodLiteral<"choice">;
+    label: z.ZodString;
+}, z.core.$strict>;
+declare const numberSchema: z.ZodObject<{
+    default: z.ZodNumber;
+    kind: z.ZodLiteral<"number">;
+    label: z.ZodString;
+    max: z.ZodOptional<z.ZodNumber>;
+    min: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+declare const textSchema: z.ZodObject<{
+    default: z.ZodString;
+    kind: z.ZodLiteral<"text">;
+    label: z.ZodString;
+}, z.core.$strict>;
+declare const listSchema: z.ZodObject<{
+    default: z.ZodArray<z.ZodString>;
+    kind: z.ZodLiteral<"list">;
+    label: z.ZodString;
+}, z.core.$strict>;
+/** A switch. Its value is `true` or `false`. */
+export type ToggleOption = z.infer<typeof toggleSchema>;
+/** One of a list of words. */
+export type ChoiceOption<C extends string = string> = Omit<z.infer<typeof choiceSchema>, "choices" | "default"> & {
+    readonly choices: readonly C[];
+    readonly default: C;
+};
+/** A number, within `min` and `max` when they are given. */
+export type NumberOption = z.infer<typeof numberSchema>;
+/** A line of text. */
+export type TextOption = z.infer<typeof textSchema>;
+/** A list of lines of text. */
+export type ListOption = Omit<z.infer<typeof listSchema>, "default"> & {
+    readonly default: readonly string[];
+};
+/** One option a shell reads. */
+export type Option = ToggleOption | ChoiceOption | NumberOption | TextOption | ListOption;
+/** Options under one key, as `clock: { format, seconds }`. */
+export type GroupOption<T extends Options = Options> = {
+    readonly kind: "group";
+    readonly options: T;
+};
+/** A shell's declared options, by key: what `options.json` holds. */
+export type Options = {
+    readonly [key: string]: Option | GroupOption;
+};
+/** What `defineOptions` takes: options, and plain objects of them as groups. */
+export type OptionsInput = {
+    readonly [key: string]: Option | OptionsInput;
+};
+/** The declaration `defineOptions` makes of `T`. */
+export type Declared<T extends OptionsInput> = {
+    readonly [K in keyof T]: T[K] extends Option ? T[K] : T[K] extends OptionsInput ? GroupOption<Declared<T[K]>> : never;
+};
+/** The value each option in `T` has. */
+export type OptionValues<T extends Options> = {
+    readonly [K in keyof T]: OptionValue<T[K]>;
+};
+/** The value an option, or a group of them, has. */
+export type OptionValue<E> = E extends GroupOption<infer G> ? OptionValues<G> : E extends ToggleOption ? boolean : E extends ChoiceOption<infer C> ? C : E extends NumberOption ? number : E extends TextOption ? string : E extends ListOption ? readonly string[] : never;
+/** The values a config gives, and why any it gave were dropped. */
+export type ReadOptions<T extends Options> = {
+    readonly values: OptionValues<T>;
+    /** One line per value dropped: where it is, and what is wrong with it. */
+    readonly dropped: readonly string[];
+};
+/** `options.json`: a shell's declared options, by key. */
+export declare const optionsSchema: z.ZodType<Options>;
+/** The option kinds, each with a label and a default. */
+export declare const option: {
+    choice: <const C extends string>(label: string, choices: readonly C[], defaultChoice: C) => ChoiceOption<C>;
+    list: (label: string, defaultList: readonly string[]) => ListOption;
+    number: (label: string, defaultNumber: number, limits?: {
+        readonly min?: number;
+        readonly max?: number;
+    }) => NumberOption;
+    text: (label: string, defaultText: string) => TextOption;
+    toggle: (label: string, defaultValue: boolean) => ToggleOption;
+};
+/**
+ * A shell's options, for its `options` export. A plain object of options is a
+ * group. Throws on a default its own choices or limits refuse.
+ */
+export declare const defineOptions: <const T extends OptionsInput>(input: T) => Declared<T>;
+/**
+ * The value of every option in `declared`: the config's where it gives a good
+ * one, the default elsewhere.
+ */
+export declare const readOptions: <T extends Options>(declared: T, given: Readonly<Record<string, unknown>> | undefined) => ReadOptions<T>;
+/**
+ * The value `given` sets for `option`, or its default where it sets none or
+ * one `option` refuses.
+ */
+export declare const readOption: <O extends Option>(option: O, given: unknown) => OptionValue<O>;
+/** What is wrong with `value` for `option`, or `undefined` if nothing is. */
+export declare const optionProblem: (option: Option, value: unknown) => string | undefined;
+/** What `watchShellOptions` needs of the desktop `Shell` is handed. */
+export type ShellOptionsHost = Pick<DomicileHost, "addEventListener" | "removeEventListener" | "shellOptions">;
+/**
+ * Call `listener` with the values of `declared` now and each time the config
+ * changes them. Returns a function that stops listening.
+ *
+ * A value the config gives that `declared` refuses is dropped, takes its
+ * default and is passed to `report`, so the shell starts whatever the config
+ * says.
+ */
+export declare const watchShellOptions: <T extends Options>(host: ShellOptionsHost, declared: T, listener: (values: OptionValues<T>) => void, report?: (dropped: string) => void) => (() => void);
+export {};

package/dist/options.js

@@ -0,0 +1,224 @@
+// The options a shell declares, their JSON form and the values a config gives
+// them. The shell exports the declaration as `options`; the builder writes it
+// to `options.json`, the Settings app draws a form from it, and the config's
+// `shell_options` holds the values. See `docs/architecture/SHELL-OPTIONS.md`.
+import { z } from "zod";
+const label = z.string().min(1);
+const toggleSchema = z.strictObject({
+    default: z.boolean(),
+    kind: z.literal("toggle"),
+    label,
+});
+const choiceSchema = z
+    .strictObject({
+    choices: z.array(z.string()).min(1),
+    default: z.string(),
+    kind: z.literal("choice"),
+    label,
+})
+    .refine((choice) => choice.choices.includes(choice.default), {
+    message: "the default is not one of the choices",
+});
+const numberSchema = z
+    .strictObject({
+    default: z.number(),
+    kind: z.literal("number"),
+    label,
+    max: z.number().optional(),
+    min: z.number().optional(),
+})
+    .refine((number) => numberProblem(number, number.default) === undefined, {
+    message: "the default is outside the limits",
+});
+const textSchema = z.strictObject({
+    default: z.string(),
+    kind: z.literal("text"),
+    label,
+});
+const listSchema = z.strictObject({
+    default: z.array(z.string()),
+    kind: z.literal("list"),
+    label,
+});
+const optionSchema = z.union([
+    toggleSchema,
+    choiceSchema,
+    numberSchema,
+    textSchema,
+    listSchema,
+]);
+const groupSchema = z.strictObject({
+    kind: z.literal("group"),
+    options: z.lazy(() => optionsSchema),
+});
+/** `options.json`: a shell's declared options, by key. */
+export const optionsSchema = z.record(z.string(), z.union([optionSchema, groupSchema]));
+/** The option kinds, each with a label and a default. */
+export const option = {
+    choice: (label, choices, defaultChoice) => ({
+        choices,
+        default: defaultChoice,
+        kind: "choice",
+        label,
+    }),
+    list: (label, defaultList) => ({
+        default: defaultList,
+        kind: "list",
+        label,
+    }),
+    number: (label, defaultNumber, limits = {}) => ({
+        default: defaultNumber,
+        kind: "number",
+        label,
+        ...limits,
+    }),
+    text: (label, defaultText) => ({
+        default: defaultText,
+        kind: "text",
+        label,
+    }),
+    toggle: (label, defaultValue) => ({
+        default: defaultValue,
+        kind: "toggle",
+        label,
+    }),
+};
+/**
+ * A shell's options, for its `options` export. A plain object of options is a
+ * group. Throws on a default its own choices or limits refuse.
+ */
+export const defineOptions = (input) => {
+    const declared = declare(input);
+    optionsSchema.parse(declared);
+    return declared;
+};
+/**
+ * The value of every option in `declared`: the config's where it gives a good
+ * one, the default elsewhere.
+ */
+export const readOptions = (declared, given) => {
+    const { dropped, values } = readGroup(declared, given ?? {}, "");
+    return {
+        dropped,
+        // The values follow `declared` key by key, which the type cannot see.
+        values: values,
+    };
+};
+/**
+ * The value `given` sets for `option`, or its default where it sets none or
+ * one `option` refuses.
+ */
+export const readOption = (option, given) => 
+// Checked against `option` just here, which the type cannot see.
+(given !== undefined && optionProblem(option, given) === undefined
+    ? given
+    : option.default);
+/** What is wrong with `value` for `option`, or `undefined` if nothing is. */
+export const optionProblem = (option, value) => {
+    switch (option.kind) {
+        case "toggle":
+            return typeof value === "boolean" ? undefined : "is not true or false";
+        case "choice":
+            return typeof value === "string" && option.choices.includes(value)
+                ? undefined
+                : `is not one of ${option.choices.join(", ")}`;
+        case "number":
+            return typeof value === "number" && Number.isFinite(value)
+                ? numberProblem(option, value)
+                : "is not a number";
+        case "text":
+            return typeof value === "string" ? undefined : "is not text";
+        case "list":
+            return Array.isArray(value) &&
+                value.every((item) => typeof item === "string")
+                ? undefined
+                : "is not a list of text";
+    }
+};
+/**
+ * Call `listener` with the values of `declared` now and each time the config
+ * changes them. Returns a function that stops listening.
+ *
+ * A value the config gives that `declared` refuses is dropped, takes its
+ * default and is passed to `report`, so the shell starts whatever the config
+ * says.
+ */
+export const watchShellOptions = (host, declared, listener, report = reportToConsole) => {
+    const heard = () => {
+        const { dropped, values } = readOptions(declared, host.shellOptions === null
+            ? undefined
+            : recordSchema.parse(JSON.parse(host.shellOptions)));
+        for (const line of dropped) {
+            report(line);
+        }
+        listener(values);
+    };
+    host.addEventListener("shelloptionschanged", heard);
+    heard();
+    return () => {
+        host.removeEventListener("shelloptionschanged", heard);
+    };
+};
+/** `input` with each plain object made a group. */
+const declare = (input) => Object.fromEntries(Object.entries(input).map(([key, entry]) => [
+    key,
+    isOption(entry) ? entry : { kind: "group", options: declare(entry) },
+]));
+const isOption = (entry) => typeof entry.kind === "string";
+const readGroup = (declared, given, at) => {
+    const unknown = Object.keys(given)
+        .filter((key) => !Object.hasOwn(declared, key))
+        .map((key) => `${at}${key}: no such option`);
+    const read = Object.entries(declared).map(([key, entry]) => ({
+        key,
+        ...readEntry(entry, given[key], `${at}${key}`),
+    }));
+    return {
+        dropped: [...read.flatMap(({ dropped }) => dropped), ...unknown].toSorted(),
+        values: Object.fromEntries(read.map(({ key, value }) => [key, value])),
+    };
+};
+const readEntry = (entry, given, at) => {
+    if (entry.kind === "group") {
+        const group = recordSchema.safeParse(given === undefined ? {} : given);
+        if (group.success) {
+            const { dropped, values } = readGroup(entry.options, group.data, `${at}.`);
+            return { dropped, value: values };
+        }
+        else {
+            return {
+                dropped: [`${at}: ${JSON.stringify(given)} is not a group of options`],
+                value: readGroup(entry.options, {}, "").values,
+            };
+        }
+    }
+    else if (given === undefined) {
+        return { dropped: [], value: entry.default };
+    }
+    else {
+        const problem = optionProblem(entry, given);
+        return problem === undefined
+            ? { dropped: [], value: given }
+            : {
+                dropped: [`${at}: ${JSON.stringify(given)} ${problem}`],
+                value: entry.default,
+            };
+    }
+};
+const recordSchema = z.record(z.string(), z.unknown());
+const reportToConsole = (dropped) => {
+    // biome-ignore lint/suspicious/noConsole: the option takes its default, and the config's author should learn why
+    console.error(`shell_options.${dropped}`);
+};
+/** Which of `limits` `value` is outside, or `undefined` if neither. */
+const numberProblem = (limits, value) => {
+    if (limits.min !== undefined && value < limits.min) {
+        return `is below ${String(limits.min)}`;
+    }
+    else if (limits.max !== undefined && value > limits.max) {
+        return `is above ${String(limits.max)}`;
+    }
+    else {
+        return undefined;
+    }
+};

package/package.json

@@ -78,6 +78,10 @@
       "types": "./dist/notification.d.ts",
       "default": "./dist/notification.js"
     },
+    "./options": {
+      "types": "./dist/options.d.ts",
+      "default": "./dist/options.js"
+    },
     "./own-keybindings": {
       "types": "./dist/own-keybindings.d.ts",
       "default": "./dist/own-keybindings.js"
@@ -128,7 +132,7 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-e77cfff77793",
+  "version": "0.0.0-alpha-5166c4cfb4be",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cprussin/domicile.git",