@openpen/module-api 1.2.0 → 1.4.0

package/dist/types/control-bar-layout.d.ts

@@ -3,166 +3,37 @@ import type { Component } from 'vue';
 import type { LocaleMap } from '../locale';
 export declare const GroupInsetSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
-    /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
     color: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    enabled: boolean;
-    color?: string | undefined;
-}, {
-    enabled: boolean;
-    color?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const LayoutGroupSchema: z.ZodObject<{
     id: z.ZodString;
-    items: z.ZodArray<z.ZodString, "many">;
-    separator: z.ZodOptional<z.ZodEnum<["auto", "always", "never"]>>;
-    /**
-     * Optional inset rendering for this group. When `enabled: true`, the group
-     * MUST render with a visible bg + border + padding container (the design's
-     * "grouped tools" look) AND its inner items MUST shrink so the group's
-     * outer height matches an unwrapped 36px button — i.e. enabling inset
-     * MUST NOT increase control-bar height.
-     */
+    items: z.ZodArray<z.ZodString>;
+    separator: z.ZodOptional<z.ZodEnum<{
+        never: "never";
+        auto: "auto";
+        always: "always";
+    }>>;
     inset: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodBoolean;
-        /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
         color: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        enabled: boolean;
-        color?: string | undefined;
-    }, {
-        enabled: boolean;
-        color?: string | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    items: string[];
-    separator?: "never" | "auto" | "always" | undefined;
-    inset?: {
-        enabled: boolean;
-        color?: string | undefined;
-    } | undefined;
-}, {
-    id: string;
-    items: string[];
-    separator?: "never" | "auto" | "always" | undefined;
-    inset?: {
-        enabled: boolean;
-        color?: string | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const ControlBarLayoutSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
-    groups: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
+    groups: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        items: z.ZodArray<z.ZodString, "many">;
-        separator: z.ZodOptional<z.ZodEnum<["auto", "always", "never"]>>;
-        /**
-         * Optional inset rendering for this group. When `enabled: true`, the group
-         * MUST render with a visible bg + border + padding container (the design's
-         * "grouped tools" look) AND its inner items MUST shrink so the group's
-         * outer height matches an unwrapped 36px button — i.e. enabling inset
-         * MUST NOT increase control-bar height.
-         */
+        items: z.ZodArray<z.ZodString>;
+        separator: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            auto: "auto";
+            always: "always";
+        }>>;
         inset: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodBoolean;
-            /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */
             color: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            enabled: boolean;
-            color?: string | undefined;
-        }, {
-            enabled: boolean;
-            color?: string | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }, {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }>, "many">, {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[], {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[]>, {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[], {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[]>, {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[], {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[]>;
-}, "strip", z.ZodTypeAny, {
-    version: 1;
-    groups: {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[];
-}, {
-    version: 1;
-    groups: {
-        id: string;
-        items: string[];
-        separator?: "never" | "auto" | "always" | undefined;
-        inset?: {
-            enabled: boolean;
-            color?: string | undefined;
-        } | undefined;
-    }[];
-}>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export interface GroupInset {
     enabled: boolean;
     /** Optional CSS color override for the inset background; defaults to --openpen-color-control-group. */

package/dist/types/module.d.ts

@@ -64,6 +64,11 @@ export interface OpenPenModule {
      * made via `ctx.updateSettings()`; writes that fail validation reject
      * with the underlying `ZodError`.
      *
+     * Nested object fields that need their inner defaults filled from an
+     * empty or invalid stored value MUST use `.prefault({})`, not
+     * `.default({})`: the host rebuilds invalid settings from `{}`, and
+     * `.default()` returns its value without parsing it.
+     *
      * Modules that intend to call `ctx.updateSettings()` MUST declare
      * this field; calling `updateSettings` without a schema throws at
      * runtime so the missing contract surfaces during development.
@@ -130,7 +135,8 @@ export interface ModuleSetupContext {
      * result against `settingsSchema` (Zod), and persists to `config.json`.
      * Resolves once the write is durable; rejects with the underlying
      * `ZodError` if the merged object fails validation (no I/O happens
-     * on validation failure).
+     * on validation failure). Read the failures from `error.issues`;
+     * `ZodError` has no `.errors` property.
      *
      * The in-memory snapshot returned by `getSettings()` is updated
      * before the Promise resolves; subscribers registered via

package/dist/types/tool.d.ts

@@ -37,6 +37,18 @@ export interface Stroke {
     tool: string;
     points: Point[];
     style: StrokeStyle;
+    /**
+     * Whole-stroke opacity in `0..1`; omitted means fully opaque.
+     *
+     * The host's default polyline renderer applies it as `globalAlpha` and clamps
+     * values outside `0..1` back into range (non-finite values are ignored). A
+     * tool that ships its own `renderStroke` owns the drawing and reads this field
+     * itself — the host does not wrap custom renderers, so a plugin that already
+     * stores and applies its own `opacity` key keeps rendering exactly as before.
+     * A tool WITHOUT `renderStroke` that stores an `opacity` key now has it applied
+     * by the default renderer; such a tool must store a number in `0..1`.
+     */
+    opacity?: number;
     /**
      * Tool-specific extra state. Tools MAY store arbitrary keys here during
      * `onPointerDown` / `onPointerMove` / `onPointerUp`; those keys survive
@@ -48,11 +60,10 @@ export interface Stroke {
      *
      * @example
      * // Store during onPointerUp:
-     * const stroke: Stroke = { id, tool: 'my-tool', points, style, opacity: 0.5 }
+     * const stroke: Stroke = { id, tool: 'my-tool', points, style, taper: 0.5 }
      *
      * // Read back in renderStroke:
-     * const opacity = (stroke.opacity as number) ?? 1
-     * canvasCtx.globalAlpha = opacity
+     * const taper = (stroke.taper as number) ?? 1
      */
     [key: string]: unknown;
 }

package/dist/uikit/components/AppButtonDropdown.vue.d.ts

@@ -35,7 +35,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     disabled: boolean;
     active: boolean;
     variant: "default" | "danger";
-    popoverPlacement: "auto" | "top" | "bottom" | "left" | "right";
+    popoverPlacement: "auto" | "left" | "right" | "top" | "bottom";
     mainTooltip: string;
     mainAriaLabel: string;
     caretAriaLabel: string;

package/dist/uikit/components/AppPopoverPanel.vue.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AppPopoverPanel - High-level wrapper (Layer 1).
+ *
+ * Inner layout for the `content` slot of AppPopover: a vertical stack with the
+ * same 10px spacing the host's own popup panels use, plus an optional title.
+ * Rows share three columns (label, control, value) so controls start at the
+ * same x in every row without any plugin-side CSS.
+ * The frame (background, border, radius, padding, shadow) comes from AppPopover.
+ *
+ * Styles use --openpen-* design tokens only.
+ */
+type __VLS_Props = {
+    /** Optional small-caps heading rendered above the panel content. */
+    title?: string;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/uikit/components/AppPopoverRow.vue.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AppPopoverRow - High-level wrapper (Layer 1).
+ *
+ * One form row inside an AppPopoverPanel: an optional label followed by a
+ * control (toggle, slider, segmented control, ...) in the default slot, and an
+ * optional third element (value text such as "150px") that is right-aligned in
+ * the panel's shared value column.
+ * Spacing matches the host's own popup rows (10px gap, vertically centred).
+ */
+type __VLS_Props = {
+    /** Optional label rendered before the control. */
+    label?: string;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/uikit/components/AppSegmented.vue.d.ts

@@ -2,13 +2,18 @@ interface Option {
     value: string;
     label: string;
     icon?: string;
+    /** Show only the icon; `label` becomes the accessible name and the tooltip. */
+    iconOnly?: boolean;
+    /** Tooltip text; defaults to `label` for icon-only options. */
+    tooltip?: string;
     testid?: string;
 }
 type __VLS_Props = {
     modelValue: string;
     options: Option[];
-    /** When true, all options are non-interactive and visually dimmed. */
     disabled?: boolean;
+    /** Accessible name of the whole group (e.g. "Head style"). */
+    ariaLabel?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: string) => any;

package/dist/uikit/components/AppSelect.vue.d.ts

@@ -14,6 +14,12 @@ export interface AppSelectProps {
     placeholder: string;
     /** Whether the select is disabled. */
     disabled?: boolean;
+    /**
+     * Accessible name of the trigger button. Pass it whenever the select has no
+     * visible label of its own; otherwise a screen reader announces only the
+     * current value.
+     */
+    ariaLabel?: string;
 }
 declare const __VLS_export: import("vue").DefineComponent<AppSelectProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: string) => any;
@@ -21,6 +27,7 @@ declare const __VLS_export: import("vue").DefineComponent<AppSelectProps, {}, {}
     "onUpdate:modelValue"?: ((value: string) => any) | undefined;
 }>, {
     disabled: boolean;
+    ariaLabel: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/uikit/components/AppSlider.vue.d.ts

@@ -5,6 +5,11 @@ type __VLS_Props = {
     step?: number;
     /** Container width (e.g. '100%', '72px'). In vertical mode this sets the height. */
     width?: string;
+    /**
+     * Accessible name announced by screen readers when the thumb is focused.
+     * Pass it whenever the slider has no visible label of its own.
+     */
+    ariaLabel?: string;
     orientation?: 'horizontal' | 'vertical';
     trackHeight?: string;
     trackRadius?: string;
@@ -21,6 +26,13 @@ type __VLS_Props = {
      * startEdge/endEdge on SliderRange — no manual value transformation needed.
      */
     inverted?: boolean;
+    /**
+     * Text for the value bubble (e.g. "4px"). When set, a small bubble with this
+     * text appears above the thumb while the slider is being dragged and hides on
+     * release; it is also exposed to assistive technology as `aria-valuetext`.
+     * Horizontal sliders only. Leave unset for no bubble.
+     */
+    valueLabel?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: number) => any;
@@ -31,6 +43,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
     min: number;
     max: number;
     step: number;
+    ariaLabel: string;
     orientation: "horizontal" | "vertical";
     trackHeight: string;
     trackRadius: string;
@@ -38,6 +51,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
     thumbHeight: string;
     thumbRadius: string;
     inverted: boolean;
+    valueLabel: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/uikit/components/AppSwatchPicker.vue.d.ts

@@ -0,0 +1,37 @@
+export interface SwatchColor {
+    /** CSS colour value, e.g. `#818CF8`. Compared case-insensitively with `modelValue`. */
+    value: string;
+    /** Accessible name announced for the swatch (for example `Indigo`). */
+    label: string;
+    /** Optional `data-testid` for the swatch button. */
+    testid?: string;
+}
+type __VLS_Props = {
+    /** Currently selected colour value (use `v-model`). */
+    modelValue: string;
+    colors: SwatchColor[];
+    /** Accessible name of the whole group. */
+    ariaLabel: string;
+    shape?: 'circular' | 'rounded' | 'square';
+    size?: 'small' | 'medium' | 'large';
+    /** Gap between swatches: `small` 6px, `medium` 8px. */
+    spacing?: 'small' | 'medium';
+    /** Swatch background override, for example a gradient. Defaults to the colour value. */
+    background?: (color: SwatchColor) => string;
+    disabled?: boolean;
+    testid?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: string) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+}>, {
+    disabled: boolean;
+    testid: string;
+    shape: "square" | "rounded" | "circular";
+    size: "small" | "medium" | "large";
+    spacing: "small" | "medium";
+    background: (color: SwatchColor) => string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/uikit/components/AppToggle.vue.d.ts

@@ -1,6 +1,7 @@
 type __VLS_Props = {
     modelValue: boolean;
     ariaLabel?: string;
+    testid?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: boolean) => any;
@@ -8,6 +9,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
     "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
 }>, {
     ariaLabel: string;
+    testid: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/uikit/components/AppToggleButton.vue.d.ts

@@ -0,0 +1,28 @@
+type __VLS_Props = {
+    /** Pressed state (use `v-model`). */
+    modelValue: boolean;
+    /** Accessible name. Required because the content is often a single glyph or icon. */
+    ariaLabel: string;
+    disabled?: boolean;
+    testid?: string;
+};
+declare var __VLS_9: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_9) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
+}>, {
+    disabled: boolean;
+    testid: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/uikit/index.d.ts

@@ -12,17 +12,23 @@
  *   Note: you must manually handle modal-manager, animating guard,
  *   passthrough, and teleport target when walking this layer.
  *
- * Layer 3 — Escape Hatch (5% fully custom)
- *   Plugin installs reka-ui (or any library) directly in its own package.json.
- *   UIKit MUST NOT block this. Not handled here — plugin author's choice.
+ * Layer 3 — Custom Components (5% fully custom)
+ *   Plugin builds its own components on top of the Layer 2 primitives and the
+ *   --openpen-* design tokens. Plugins MUST NOT install or import reka-ui
+ *   directly; headless primitives come only from this entry point.
  *
  * See docs/uikit/index.md for the full trade-off description.
  */
 export { default as AppPopover } from './components/AppPopover.vue';
 export type { AppPopoverProps, Placement } from './components/AppPopover.vue';
+export { default as AppPopoverPanel } from './components/AppPopoverPanel.vue';
+export { default as AppPopoverRow } from './components/AppPopoverRow.vue';
 export { default as AppSlider } from './components/AppSlider.vue';
 export { default as AppToggle } from './components/AppToggle.vue';
 export { default as AppSegmented } from './components/AppSegmented.vue';
+export { default as AppSwatchPicker } from './components/AppSwatchPicker.vue';
+export type { SwatchColor } from './components/AppSwatchPicker.vue';
+export { default as AppToggleButton } from './components/AppToggleButton.vue';
 export { default as AppDialog } from './components/AppDialog.vue';
 export type { AppDialogProps } from './components/AppDialog.vue';
 export { useDialog } from './composables/useDialog';