{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://atsurae.app/docs/schema/widget.schema.json",
  "title": "Atsurae widget",
  "description": "A widget for Atsurae: text, images, shapes and progress bars that float over the wallpaper on the desktop. Docs: https://atsurae.app/docs/reference/widget-json/",
  "type": "object",
  "required": ["formatVersion", "id", "name", "elements"],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "description": "This schema's URL, so your editor can check the file and suggest fields. Atsurae ignores it."
    },
    "formatVersion": {
      "type": "integer",
      "enum": [1, 2],
      "description": "The widget format this file uses. Use 2. Format 1 widgets (text only) still work."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]*$",
      "description": "A unique ID: lowercase letters, numbers and dashes, like \"world-clock\". Atsurae remembers where the widget is placed by this ID, so don't change it after sharing."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name shown in Atsurae, like \"World Clock\"."
    },
    "summary": {
      "type": "string",
      "description": "One sentence shown under the name in the Library."
    },
    "author": {
      "type": "string",
      "description": "Who made the widget."
    },
    "version": {
      "type": "string",
      "description": "Your own version number, like \"1.2\". Atsurae doesn't use it."
    },
    "options": {
      "type": "array",
      "description": "Settings people can change in Customize Widgets. Their values are available as tokens ({key}) and in scripts (context.options).",
      "items": { "$ref": "#/$defs/option" }
    },
    "elements": {
      "type": "array",
      "minItems": 1,
      "description": "What to draw, in order (later elements draw on top). Each is positioned relative to where the widget is placed.",
      "items": { "$ref": "#/$defs/element" }
    },
    "script": {
      "type": "object",
      "description": "JavaScript that computes values for {script.<name>} tokens. The widget must be a .atsuraewidget folder with the script inside.",
      "required": ["file"],
      "additionalProperties": false,
      "properties": {
        "file": {
          "type": "string",
          "description": "The script's path in the widget's folder, usually \"script.js\". It must define function update(context)."
        },
        "updateEvery": {
          "description": "How often update(context) runs: \"minute\" (the default), \"second\", or a number of seconds (at least 1). It also runs when the battery, the playing song or the weather changes.",
          "oneOf": [
            { "type": "string", "enum": ["minute", "second"] },
            { "type": "number", "minimum": 1 }
          ]
        }
      }
    }
  },
  "$defs": {
    "color": {
      "type": "string",
      "pattern": "^#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$",
      "description": "A color as #RRGGBB, or #RRGGBBAA with transparency (#FFFFFF80 is half-transparent white)."
    },
    "size": {
      "type": "array",
      "items": { "type": "number", "minimum": 0 },
      "minItems": 2,
      "maxItems": 2,
      "description": "[width, height] as fractions of the screen height. [0.1, 0.1] is a square a tenth of the screen tall."
    },
    "option": {
      "type": "object",
      "required": ["key", "label", "kind", "defaultValue"],
      "additionalProperties": false,
      "properties": {
        "key": {
          "type": "string",
          "description": "The name used in tokens ({key}), visibleWhen (\"key=value\") and scripts (context.options.key). use24Hour, showSeconds and text also change built-in tokens; see the docs."
        },
        "label": { "type": "string", "description": "The label shown next to the control." },
        "kind": {
          "type": "string",
          "enum": ["toggle", "text", "choice"],
          "description": "toggle: a switch (\"true\" or \"false\"). text: a text field. choice: a menu of choices."
        },
        "defaultValue": {
          "type": "string",
          "description": "The starting value, always as text: \"true\"/\"false\" for toggles, one of choices for a choice."
        },
        "choices": {
          "type": "array",
          "items": { "type": "string" },
          "description": "For kind choice: the possible values."
        },
        "choiceLabels": {
          "type": "array",
          "items": { "type": "string" },
          "description": "For kind choice: what to show for each value, in the same order."
        }
      }
    },
    "font": {
      "type": "object",
      "required": ["size"],
      "additionalProperties": false,
      "properties": {
        "family": {
          "type": "string",
          "description": "A font family: \"Michroma\" (comes with Atsurae), a font in the widget's fonts/ folder, or any font installed on the Mac. Leave it out for the system font (SF Pro)."
        },
        "weight": {
          "type": "string",
          "enum": ["ultraLight", "thin", "light", "regular", "medium", "semibold", "bold", "heavy", "black"],
          "description": "How bold the text is. Fonts that don't have that weight use their closest one."
        },
        "size": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "The text size as a fraction of the screen height. 0.02 is small, 0.05 is large, 0.15 is huge."
        }
      }
    },
    "element": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "type": {
          "type": "string",
          "enum": ["text", "image", "shape", "progress"],
          "description": "What to draw. Text when left out."
        },
        "text": {
          "type": "string",
          "description": "Text elements: the text, with {tokens} like {time}, {weekday|upper} or {script.greeting}."
        },
        "font": { "$ref": "#/$defs/font" },
        "tracking": {
          "type": "number",
          "description": "Text elements: extra space between letters, in ems (0.1 is a little, 0.4 is wide). Negative values tighten."
        },
        "src": {
          "type": "string",
          "description": "Image elements: the image's path in the widget's folder, like \"images/moon.png\". PNG, JPEG, HEIC, GIF (first frame), PDF and SVG."
        },
        "tint": {
          "$ref": "#/$defs/color",
          "description": "Image elements: fills the image's shape with this color, for single-color icons. The color someone picks in Customize Widgets replaces it."
        },
        "shape": {
          "type": "string",
          "enum": ["rect", "circle", "line"],
          "description": "Shape elements: rect (the default; rounded with cornerRadius), circle (an ellipse filling size) or line (horizontal, as wide as size)."
        },
        "fill": {
          "$ref": "#/$defs/color",
          "description": "Shape elements: the inside color. Without fill or stroke, shapes are filled with color (or white)."
        },
        "stroke": {
          "$ref": "#/$defs/color",
          "description": "Shape elements: the outline color (the line's color, for lines)."
        },
        "strokeWidth": {
          "type": "number",
          "minimum": 0,
          "description": "Shape elements: the outline's thickness as a fraction of the screen height. Default 0.002; lines default to their size's height."
        },
        "style": {
          "type": "string",
          "enum": ["bar", "ring"],
          "description": "Progress elements: a horizontal bar (the default) or a ring that fills clockwise from the top."
        },
        "value": {
          "type": "string",
          "description": "Progress elements: a number from 0 to 1, usually a token like \"{battery.level}\", \"{year.progress}\" or \"{script.progress}\". Numbers ending in % are divided by 100."
        },
        "lineWidth": {
          "type": "number",
          "minimum": 0,
          "description": "Progress elements: the thickness as a fraction of the screen height. Bars default to their height; rings to 0.006."
        },
        "track": {
          "$ref": "#/$defs/color",
          "description": "Progress elements: the color of the unfilled part. Default #FFFFFF40."
        },
        "size": { "$ref": "#/$defs/size" },
        "cornerRadius": {
          "type": "number",
          "minimum": 0,
          "description": "Images and rect shapes: how round the corners are, as a fraction of the screen height."
        },
        "color": {
          "$ref": "#/$defs/color",
          "description": "Text color, progress fill or line color. Default white. The color someone picks in Customize Widgets replaces text and progress colors."
        },
        "opacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "0 is invisible, 1 is solid (the default)."
        },
        "shadow": {
          "type": "boolean",
          "description": "A soft shadow that keeps the element readable on bright wallpapers. On unless set to false."
        },
        "offset": {
          "type": "array",
          "items": { "type": "number" },
          "minItems": 2,
          "maxItems": 2,
          "description": "[x, y] from the widget's position, as fractions of the screen height. Positive y moves down."
        },
        "alignment": {
          "type": "string",
          "enum": ["center", "leading", "trailing"],
          "description": "Which edge sits at the position: center (the default), leading (left edge) or trailing (right edge). Elements are always centered vertically."
        },
        "visibleWhen": {
          "type": "string",
          "description": "Only draw the element when an option has a value (\"use24Hour=false\"), or while a token isn't empty, \"false\" or \"0\" (\"{track}\", \"{script.showAlert}\")."
        },
        "hideWhenEmpty": {
          "type": "boolean",
          "description": "Text elements: hide the text while every token in it is empty, like {track} when nothing is playing."
        }
      },
      "allOf": [
        {
          "if": { "properties": { "type": { "const": "image" } }, "required": ["type"] },
          "then": { "required": ["src", "size"] }
        },
        {
          "if": { "properties": { "type": { "const": "shape" } }, "required": ["type"] },
          "then": { "required": ["size"] }
        },
        {
          "if": { "properties": { "type": { "const": "progress" } }, "required": ["type"] },
          "then": { "required": ["value", "size"] }
        },
        {
          "if": { "not": { "required": ["type"] } },
          "then": { "required": ["text"] }
        },
        {
          "if": { "properties": { "type": { "const": "text" } }, "required": ["type"] },
          "then": { "required": ["text"] }
        }
      ]
    }
  }
}
