@navbytes/vee 0.3.0 → 0.5.0

package/README.md

@@ -48,6 +48,10 @@ The examples in this repository import `../vee.ts` because they sit next to the
 SDK here. Copying one out means running `vee sdk ts` beside it and changing that
 import to `./vee.ts`.
 
+For a new plugin, prefer `JSONMenu` over `Menu` — see
+[`examples/json-demo.ts`](examples/json-demo.ts) and the
+[JSON output format](https://vee.navbytes.io/guide/json-output/) docs.
+
 ## Layout
 
 ```

package/dist/vee.d.ts

@@ -1,4 +1,13 @@
 export type Color = string;
+/**
+ * One presentation of a plugin's menu, in the vocabulary `visibleOn` takes:
+ * the menu-bar dropdown, the transient search panel, a detached window, and
+ * terminal listings (`vee search`).
+ *
+ * There is deliberately no `"widget"`: menu rows never reach the widget, which
+ * a plugin targets whole with `<vee.surface>`.
+ */
+export type Surface = "menu" | "search" | "window" | "cli";
 export interface ItemOptions {
     color?: Color;
     size?: number;
@@ -16,7 +25,11 @@ export interface ItemOptions {
     params?: string[];
     terminal?: boolean;
     refresh?: boolean;
-    /** Show this line in the dropdown only, never in the menu bar. */
+    /**
+     * Show this line in the dropdown only, never in the menu bar. On a dropdown
+     * row `dropdown: false` is the older spelling of "on no surface at all";
+     * `visibleOn` says the same thing precisely, and wins when both are set.
+     */
     dropdown?: boolean;
     alternate?: boolean;
     disabled?: boolean;
@@ -64,6 +77,19 @@ export interface ItemOptions {
      * share the same in-row geometry. Omitted, the accessory sits trailing.
      */
     accessory?: "leading" | "trailing";
+    /**
+     * The surfaces this row exists on → `visibleon=menu,window`. Omitted, the row
+     * exists on all of them — targeting only ever subtracts, and it takes the
+     * row's whole subtree with it.
+     */
+    visibleOn?: Surface[];
+    /**
+     * `false` keeps the row out of every filter query's reach — the search panel,
+     * a window's filter field, and `vee search` — while leaving it visible and
+     * clickable in an idle listing. A separate axis from `visibleOn`: where a row
+     * exists and whether a query can reach it are different questions.
+     */
+    searchable?: boolean;
     /** Inline data series → `sparkline=1,2,3`. */
     sparkline?: number[];
     /**
@@ -173,6 +199,19 @@ export interface WidgetCardItem {
     value?: string;
     symbol?: string;
     tint?: Color;
+    /**
+     * Makes this `list`/`board` row a tap target that opens a URL.
+     * Scheme-filtered by Vee on parse, exactly like an `href` action's; a blocked
+     * URL drops the tap and leaves the row inert, keeping its data.
+     */
+    url?: string;
+    /**
+     * Makes this row a tap target that runs a named macOS Shortcut. A row
+     * declaring both opens its `url` — the same href-before-shortcut precedence
+     * the menu applies. There is deliberately no `shell`: a widget row must not
+     * run an arbitrary command without the menu's context.
+     */
+    shortcut?: string;
 }
 export interface WidgetCardAction {
     kind: WidgetActionKind;
@@ -237,7 +276,9 @@ export interface NodeStyle {
     /** Grow to fill available width (the only, bounded, width control). */
     fill?: boolean;
 }
-export type NodeType = "vstack" | "hstack" | "zstack" | "grid" | "text" | "image" | "gauge" | "sparkline" | "spacer" | "divider";
+export type NodeType = "vstack" | "hstack" | "zstack" | "grid" | "text" | "image" | "gauge" | "sparkline" | "chart" | "spacer" | "divider";
+/** The three share-chart shapes, spelled as they are on a menu row. */
+export type ChartNodeKind = "pie" | "donut" | "stackedbar";
 export interface WidgetNode {
     type: NodeType;
     text?: string;
@@ -245,10 +286,16 @@ export interface WidgetNode {
     symbol?: string;
     /** `0…1` fill, for a `gauge` node. */
     value?: number;
-    /** Series, for a `sparkline` node. */
+    /** Series, for a `sparkline` node, or segment magnitudes for a `chart` one. */
     values?: number[];
     /** `"linear"` (default) or `"circular"`, for a `gauge` node. */
     gaugeStyle?: "linear" | "circular";
+    /** The shape, for a `chart` node. Unknown kinds drop the leaf. */
+    kind?: ChartNodeKind;
+    /** Per-segment names, for a `chart` node. May be shorter than `values`. */
+    labels?: string[];
+    /** Per-segment colors, for a `chart` node. Recolors a prefix; unset segments take the palette. */
+    colors?: Color[];
     /** Cross-axis alignment, for a container. */
     align?: string;
     /** Inter-child spacing, for a container. */
@@ -312,6 +359,17 @@ export declare const Node: {
     } & LeafOpts) => WidgetNode;
     /** A dependency-free line chart from `values`. */
     Sparkline: (values: number[], opts?: LeafOpts) => WidgetNode;
+    /**
+     * A share chart — the same `pie`/`donut`/`stackedbar` a menu row draws, from
+     * one series of non-negative values read as shares of a whole. `labels` and
+     * `colors` are positional against `values` and may be shorter; an unset
+     * segment takes its slot in Vee's eight-color categorical palette. A series
+     * longer than eight is folded (not truncated) into a trailing `Other`.
+     */
+    Chart: (kind: ChartNodeKind, values: number[], opts?: {
+        labels?: string[];
+        colors?: Color[];
+    } & LeafOpts) => WidgetNode;
     /** Flexible empty space. */
     Spacer: (opts?: {
         minLength?: number;
@@ -353,6 +411,10 @@ export interface JSONItemOptions {
     tooltip?: string;
     header?: boolean;
     accessory?: "leading" | "trailing";
+    /** The surfaces this item exists on; absent = all of them. */
+    visibleOn?: Surface[];
+    /** `false` keeps the item out of every filter query, but still browsable. */
+    searchable?: boolean;
     sparkline?: number[];
     /** Sparkline width in points; `"full"` stretches it to the row's width. */
     /** @deprecated Use `accessoryWidth`. */

package/dist/vee.js

@@ -75,6 +75,9 @@ function encode(options) {
     push("shortcut", options.shortcut);
     push("header", options.header);
     push("accessory", options.accessory);
+    if (options.visibleOn !== undefined)
+        push("visibleon", options.visibleOn.join(","));
+    push("searchable", options.searchable);
     if (options.sparkline !== undefined)
         push("sparkline", options.sparkline.map(String).join(","));
     push("sparklinecolor", options.sparklineColor);
@@ -205,6 +208,9 @@ function orderNode(n) {
     put("value", n.value);
     put("values", n.values);
     put("gauge_style", n.gaugeStyle);
+    put("kind", n.kind);
+    put("labels", n.labels);
+    put("colors", n.colors);
     put("align", n.align);
     put("spacing", n.spacing);
     put("columns", n.columns);
@@ -261,6 +267,14 @@ export const Node = {
     Gauge: (value, opts = {}) => ({ type: "gauge", value, ...opts }),
     /** A dependency-free line chart from `values`. */
     Sparkline: (values, opts = {}) => ({ type: "sparkline", values, ...opts }),
+    /**
+     * A share chart — the same `pie`/`donut`/`stackedbar` a menu row draws, from
+     * one series of non-negative values read as shares of a whole. `labels` and
+     * `colors` are positional against `values` and may be shorter; an unset
+     * segment takes its slot in Vee's eight-color categorical palette. A series
+     * longer than eight is folded (not truncated) into a trailing `Other`.
+     */
+    Chart: (kind, values, opts = {}) => ({ type: "chart", kind, values, ...opts }),
     /** Flexible empty space. */
     Spacer: (opts = {}) => ({ type: "spacer", ...opts }),
     /** A hairline divider. */
@@ -290,6 +304,7 @@ export function Board(options) {
 const JSON_ITEM_KEYS = [
     "text", "separator", "color", "size", "href", "shell", "params", "terminal",
     "refresh", "sfimage", "disabled", "checked", "tooltip", "header", "accessory",
+    "visibleOn", "searchable",
     "sparkline", "sparklineWidth", "sparklineHeight", "sparklineColor",
     "accessoryWidth", "accessoryHeight",
     "toggle", "slider", "progress", "progressTrackColor", "progressWidth",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navbytes/vee",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Typed builders for authoring Vee plugins — the xbar/SwiftBar text protocol, the structured-JSON menu format, and widget cards.",
   "keywords": [