glance-widgets-sdk 1.0.0__py3-none-any.whl

glance_widgets/__init__.py

@@ -0,0 +1,138 @@
+"""Glance Widgets SDK: native Python builders for protocol v1."""
+
+from .color import (
+    parse_color,
+    format_color,
+    normalize_color,
+    is_app_color,
+    rgb,
+    with_alpha,
+    mix_colors,
+)
+from .geometry import (
+    Box,
+    require_canvas,
+    resolve_frame,
+    fit_matrix,
+    cell_rect,
+    column_boundary,
+    row_boundary,
+    to_ratio_rect,
+    solve_grid,
+    GAP_MODE_RATIOS,
+    FRAME_DECIMALS,
+)
+from .matrix import Matrix, EMPTY, DEFAULT_PIXEL_BASE, BATCH_MIN_OCCURRENCES
+from .font import (
+    PixelFont,
+    define_font,
+    get_font,
+    resolve_font,
+    measure_text,
+    layout_text,
+    FONT_3X5,
+    FONT_5X7,
+    DEFAULT_FONT_NAME,
+    DEFAULT_LETTER_SPACING,
+    DEFAULT_LINE_SPACING,
+    ANCHOR_BOX_WIDTH,
+)
+from .text_matrix import text_matrix
+from .themes import (
+    themes,
+    get_theme,
+    theme_options,
+    OFF_PIXEL_OPACITY,
+    ROOT_RING_OPACITY_THRESHOLD,
+)
+from .icons import has_icon, icon_names, icon_glyph, DEFAULT_ICON_NAME
+from .layers import (
+    text,
+    line,
+    horizontal_line,
+    vertical_line,
+    shape,
+    icon,
+    image,
+    curve,
+    TEXT_DEFAULTS,
+    LINE_DEFAULTS,
+    SHAPE_DEFAULTS,
+    ICON_DEFAULTS,
+    IMAGE_DEFAULTS,
+    CURVE_DEFAULTS,
+)
+from .output import layer_path, layer_id, nest_at_path, merge, place, empty_root, to_response
+from .protocol import (
+    validate,
+    resolve_data_path,
+    GlanceValidationError,
+    PROTOCOL_VERSION,
+    MAX_RESPONSE_BYTES,
+    MAX_MATRIX_CELLS,
+    LAYER_ID_PREFIX,
+    MAX_SAFE_NATIVE_INTEGER,
+    DATA_PATH_PATTERN,
+    CELL_ASPECT_RATIO_MIN,
+    CELL_ASPECT_RATIO_MAX,
+    EDGE_INSET_RATIO_LIMIT,
+    GAP_RATIO_MAX,
+    FRAME_SIZE_MIN,
+    FRAME_SIZE_MAX,
+    SHAPE_MIN_SIZE_PT,
+)
+from .raster import RASTER_MAX_EXTENT, RASTER_MAX_COORDINATE, ARC_DIRECTION_SCALE
+from .signature import (
+    sign,
+    verify_signature,
+    TIMESTAMP_HEADER,
+    SIGNATURE_HEADER,
+    DEFAULT_SIGNATURE_TOLERANCE_MS,
+)
+from .pixelate import pixelate, DEFAULT_ALPHA_THRESHOLD
+from .pixel_progress import (
+    pixel_progress_bar,
+    labeled_pixel_progress_bar,
+    pixel_ring_progress,
+    labeled_pixel_ring_progress,
+    PIXEL_PROGRESS_BAR_DEFAULTS,
+    LABELED_PIXEL_PROGRESS_BAR_DEFAULTS,
+    PIXEL_RING_PROGRESS_DEFAULTS,
+    LABELED_PIXEL_RING_PROGRESS_DEFAULTS,
+)
+from .modern import (
+    progress_bar,
+    ring_progress,
+    bar_chart,
+    battery,
+    signal,
+    arc_pieces,
+    PROGRESS_BAR_DEFAULTS,
+    RING_PROGRESS_DEFAULTS,
+    BAR_CHART_DEFAULTS,
+    BATTERY_DEFAULTS,
+    SIGNAL_DEFAULTS,
+    BAD_LEVEL,
+    WARN_LEVEL,
+)
+from .status import (
+    status_strip,
+    labeled_status_strip,
+    STATUS_STRIP_DEFAULTS,
+    LABELED_STATUS_STRIP_DEFAULTS,
+)
+from .pixel_text import pixel_text_panel, pixel_text_root, PIXEL_TEXT_DEFAULTS
+from ._shared import STATUS_COLORS, DEFAULT_THEME_NAME, percent_label
+from .heatmap import (
+    heatmap,
+    calendar_heatmap,
+    labeled_calendar_heatmap,
+    HEATMAP_DEFAULTS,
+    CALENDAR_HEATMAP_DEFAULTS,
+    LABELED_CALENDAR_HEATMAP_DEFAULTS,
+)
+from .pixel_bar_chart import pixel_bar_chart, PIXEL_BAR_CHART_DEFAULTS
+from .line_chart import line_chart, area_chart, sparkline, LINE_CHART_DEFAULTS
+from .stat import stat, STAT_DEFAULTS
+
+from .protocol import validate_layer_node

glance_widgets/_opt.py

@@ -0,0 +1,6 @@
+"""Option lookup where None means unset (TypeScript `??`)."""
+
+
+def opt(options, key, default=None):
+    value = None if options is None else options.get(key)
+    return default if value is None else value

glance_widgets/_shared.py

@@ -0,0 +1,225 @@
+"""Internal component layout and formatting helpers."""
+
+import json
+import math
+from pathlib import Path
+import re
+from ._opt import opt
+from .color import clamp, js_round
+from .geometry import Box, require_canvas, resolve_frame, solve_grid
+from .layers import text
+from .themes import get_theme
+
+DEFAULT_THEME_NAME = "lcd"
+STATUS_COLORS = dict(good="#34C759", warn="#FF9F0A", bad="#FF453A", neutral="#8E8E93")
+TEXT_LINE_HEIGHT = 1.2
+LABEL_BOX_LINES = 1.5
+LABEL_GAP_EM = 0.4
+_advances = json.loads((Path(__file__).parent / "data/text-advances.json").read_text())
+
+
+def resolve_theme(theme=None):
+    return (
+        get_theme(DEFAULT_THEME_NAME if theme is None else theme)
+        if theme is None or isinstance(theme, str)
+        else theme
+    )
+
+
+def resolve_area(frame, canvas):
+    if frame is None:
+        return Box.canvas(canvas)
+    return (
+        Box(frame.left, frame.top, frame.width, frame.height, canvas)
+        if isinstance(frame, Box)
+        else Box.from_frame(frame, canvas)
+    )
+
+
+def emitted_region(box, canvas):
+    frame = box.to_frame()
+    return dict(frame=frame, rect=resolve_frame(frame, canvas))
+
+
+def region_of(options, what):
+    canvas, frame = options.get("canvas"), options.get("frame")
+    if canvas is None:
+        if isinstance(frame, Box) and frame._canvas is not None:
+            return frame.to_pt()
+        if frame is not None:
+            raise ValueError(what + ": a frame needs a canvas")
+        return None
+    return emitted_region(resolve_area(frame, require_canvas(canvas, what)), canvas)[
+        "rect"
+    ]
+
+
+def plan_grid(region, size, theme, what):
+    if region is None:
+        if size.get("columns") is None or size.get("rows") is None:
+            raise ValueError(what + ": grid needs both counts without canvas")
+        return dict(
+            columns=size["columns"], rows=size["rows"], layout=dict(theme["layout"])
+        )
+    return solve_grid(
+        dict(
+            region=region,
+            **{k: v for k, v in size.items() if v is not None},
+            gapMode=theme["layout"]["gapMode"],
+            clampAspect=True,
+        )
+    )
+
+
+def pixel_looks(theme, colors=None):
+    colors = colors or {}
+    off = (
+        {**theme["default"], "color": colors["off"]}
+        if colors.get("off")
+        else theme["default"]
+    )
+    return dict(
+        on=opt(colors, "on", theme["palette"]["on"]),
+        off="empty" if "off" in colors and colors["off"] is None else off,
+    )
+
+
+def text_advance_em(content):
+    return (
+        sum(
+            (
+                _advances["ascii"][ord(c) - 32]
+                if 32 <= ord(c) < 127
+                else _advances["extra"].get(c, 1000)
+            )
+            + 40
+            for c in content
+        )
+        / 1000
+    )
+
+
+def text_advance_pt(content, font_pt):
+    return text_advance_em(content) * font_pt
+
+
+def estimate_text_width_pt(content, font_pt):
+    return text_advance_em(content) * 1.05 * font_pt + 1
+
+
+def font_pt_for_width(content, width):
+    return max(0, width - 1) / max(1e-9, text_advance_em(content) * 1.05)
+
+
+def text_box_height_pt(font_pt, lines=1):
+    return lines * 1.2 * font_pt + 1
+
+
+def font_pt_of(ratio, canvas):
+    return ratio * min(canvas["width"], canvas["height"])
+
+
+def font_ratio_of(pt, canvas):
+    return clamp(pt / min(canvas["width"], canvas["height"]), 0.02, 0.28)
+
+
+def resolve_identity(options, default_id, what):
+    identity = opt(options, "id", default_id)
+    path = opt(options, "path")
+    if path is None and not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", identity):
+        raise ValueError(what + ": non-identifier id needs an explicit path")
+    return identity, path if path is not None else "data." + identity
+
+
+def to_fixed(value, decimals):
+    """Round the exact IEEE double, with decimal ties away from zero (ECMAScript)."""
+    if isinstance(decimals, bool) or not isinstance(decimals, (int, float)):
+        raise ValueError("decimals must be a number in 0..100")
+    if decimals != decimals:  # NaN -> 0 (ToIntegerOrInfinity)
+        decimals = 0
+    if not math.isfinite(decimals) or not 0 <= math.trunc(decimals) <= 100:
+        raise ValueError("decimals must be in 0..100")
+    decimals = math.trunc(decimals)
+    value = float(value)
+    if value != value:
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if abs(value) >= 1e21:
+        return repr(value)
+    numerator, denominator = abs(value).as_integer_ratio()
+    scaled = numerator * 10**decimals
+    rounded, remainder = divmod(scaled, denominator)
+    if remainder * 2 >= denominator:
+        rounded += 1
+    digits = str(rounded).rjust(decimals + 1, "0")
+    result = digits[:-decimals] + "." + digits[-decimals:] if decimals else digits
+    return ("-" if value < 0 else "") + result
+
+
+def format_number(value, decimals):
+    result = to_fixed(value, decimals)
+    return to_fixed(0, decimals) if float(result) == 0 else result
+
+
+def default_decimals(*values):
+    return 0 if all(float(v).is_integer() for v in values) else 1
+
+
+def fraction_of(value, minimum, maximum):
+    if (
+        not isinstance(value, (int, float))
+        or isinstance(value, bool)
+        or not math.isfinite(value)
+    ):
+        raise ValueError("Value must be finite")
+    return (
+        clamp((value - minimum) / (maximum - minimum), 0, 1) if maximum > minimum else 0
+    )
+
+
+def require_range(what, minimum, maximum):
+    valid_numbers = all(
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+        for value in (minimum, maximum)
+    )
+    if not valid_numbers or maximum <= minimum:
+        raise ValueError(what + ": max must be greater than min")
+
+
+def require_positive_integer(what, name, value):
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or int(value) != value
+        or value < 1
+    ):
+        raise ValueError(what + ": " + name + " must be a positive integer")
+
+
+def label_layer(s):
+    style = dict(
+        color=s["color"],
+        textOpacity=s["opacity"],
+        fontSizeRatio=s["fontSizeRatio"],
+        horizontalAlignment=s["horizontal"],
+        verticalAlignment=s["vertical"],
+    )
+    if "fontWeight" in s:
+        style["fontWeight"] = s["fontWeight"]
+    return text(
+        dict(
+            id=s["id"],
+            frame=s["box"],
+            text=s["content"],
+            zIndex=s["zIndex"],
+            style=style,
+        )
+    )
+
+
+def percent_label(fraction):
+    return str(js_round(fraction * 100)) + "%"

glance_widgets/color.py

@@ -0,0 +1,95 @@
+"""Protocol colors use alpha first: #AARRGGBB."""
+
+import math
+import re
+
+
+def js_round(value):
+    if not math.isfinite(value):  # NaN/Infinity pass through like Math.round
+        return value
+    return math.floor(value + 0.5)
+
+
+def js_div(a, b):
+    """a / b with IEEE results (Infinity/NaN) instead of ZeroDivisionError."""
+    if b == 0:
+        if a == 0 or a != a:
+            return math.nan
+        return math.copysign(math.inf, a) * math.copysign(1.0, b)
+    return a / b
+
+
+def clamp(value, low, high):
+    if value != value:  # NaN propagates like Math.min/Math.max
+        return value
+    return min(high, max(low, value))
+
+
+JS_WHITESPACE = "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680" \
+    "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a" \
+    "\u2028\u2029\u202f\u205f\u3000\ufeff"
+
+
+def parse_color(color):
+    if not isinstance(color, str):
+        raise ValueError("Invalid color: expected #RGB, #RRGGBB or #AARRGGBB")
+    color = color.strip(JS_WHITESPACE)
+    if not re.fullmatch(
+        r"#?(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})", color
+    ):
+        raise ValueError("Invalid color: expected #RGB, #RRGGBB or #AARRGGBB")
+    code = color.lstrip("#")
+    if len(code) == 3:
+        code = "".join(c * 2 for c in code)
+    if len(code) == 6:
+        code = "FF" + code
+    return dict(
+        zip(("a", "r", "g", "b"), (int(code[i : i + 2], 16) for i in range(0, 8, 2)))
+    )
+
+
+def _js_number_text(v):
+    if isinstance(v, float) and v != v:
+        return "NaN"
+    if isinstance(v, float) and math.isinf(v):
+        return "Infinity" if v > 0 else "-Infinity"
+    return str(v)
+
+
+def format_color(color):
+    def channel(v):
+        if (
+            isinstance(v, bool)
+            or not isinstance(v, (int, float))
+            or not math.isfinite(v)
+        ):
+            raise ValueError("Invalid color channel " + _js_number_text(v))
+        return clamp(js_round(v), 0, 255)
+
+    values = {k: channel(color[k]) for k in ("r", "g", "b", "a")}
+    code = "".join(f"{values[k]:02X}" for k in ("r", "g", "b"))
+    return "#" + (f"{values['a']:02X}" if values["a"] != 255 else "") + code
+
+
+def normalize_color(color):
+    return format_color(parse_color(color))
+
+
+def is_app_color(color):
+    return isinstance(color, str) and bool(
+        re.fullmatch(r"#?(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})", color)
+    )
+
+
+def rgb(r, g, b, alpha=1):
+    return format_color(dict(r=r, g=g, b=b, a=alpha * 255))
+
+
+def with_alpha(color, alpha):
+    return format_color({**parse_color(color), "a": alpha * 255})
+
+
+def mix_colors(start, end, t):
+    a, b = parse_color(start), parse_color(end)
+    t = clamp(t, 0, 1)
+    return format_color({k: a[k] + (b[k] - a[k]) * t for k in a})

glance_widgets/data/fonts/font-3x5.json

@@ -0,0 +1,120 @@
+{
+  "name": "3x5",
+  "height": 5,
+  "descent": 0,
+  "spacing": 1,
+  "fallback": "?",
+  "aliases": {
+    "a": "A",
+    "b": "B",
+    "c": "C",
+    "d": "D",
+    "e": "E",
+    "f": "F",
+    "g": "G",
+    "h": "H",
+    "i": "I",
+    "j": "J",
+    "k": "K",
+    "l": "L",
+    "m": "M",
+    "n": "N",
+    "o": "O",
+    "p": "P",
+    "q": "Q",
+    "r": "R",
+    "s": "S",
+    "t": "T",
+    "u": "U",
+    "v": "V",
+    "w": "W",
+    "x": "X",
+    "y": "Y",
+    "z": "Z"
+  },
+  "glyphs": {
+    "A": [".#.", "#.#", "###", "#.#", "#.#"],
+    "B": ["##.", "#.#", "##.", "#.#", "##."],
+    "C": [".##", "#..", "#..", "#..", ".##"],
+    "D": ["##.", "#.#", "#.#", "#.#", "##."],
+    "E": ["###", "#..", "##.", "#..", "###"],
+    "F": ["###", "#..", "##.", "#..", "#.."],
+    "G": [".##", "#..", "#.#", "#.#", ".##"],
+    "H": ["#.#", "#.#", "###", "#.#", "#.#"],
+    "I": ["###", ".#.", ".#.", ".#.", "###"],
+    "J": ["..#", "..#", "..#", "#.#", ".#."],
+    "K": ["#.#", "#.#", "##.", "#.#", "#.#"],
+    "L": ["#..", "#..", "#..", "#..", "###"],
+    "M": ["#.#", "###", "###", "#.#", "#.#"],
+    "N": ["##.", "#.#", "#.#", "#.#", "#.#"],
+    "O": [".#.", "#.#", "#.#", "#.#", ".#."],
+    "P": ["##.", "#.#", "##.", "#..", "#.."],
+    "Q": [".#.", "#.#", "#.#", "##.", ".##"],
+    "R": ["##.", "#.#", "##.", "#.#", "#.#"],
+    "S": [".##", "#..", ".#.", "..#", "##."],
+    "T": ["###", ".#.", ".#.", ".#.", ".#."],
+    "U": ["#.#", "#.#", "#.#", "#.#", "###"],
+    "V": ["#.#", "#.#", "#.#", "#.#", ".#."],
+    "W": ["#.#", "#.#", "###", "###", "#.#"],
+    "X": ["#.#", "#.#", ".#.", "#.#", "#.#"],
+    "Y": ["#.#", "#.#", ".#.", ".#.", ".#."],
+    "Z": ["###", "..#", ".#.", "#..", "###"],
+    "0": ["###", "#.#", "#.#", "#.#", "###"],
+    "1": [".#.", "##.", ".#.", ".#.", "###"],
+    "2": ["##.", "..#", ".#.", "#..", "###"],
+    "3": ["##.", "..#", ".#.", "..#", "##."],
+    "4": ["#.#", "#.#", "###", "..#", "..#"],
+    "5": ["###", "#..", "##.", "..#", "##."],
+    "6": [".##", "#..", "###", "#.#", "###"],
+    "7": ["###", "..#", ".#.", ".#.", ".#."],
+    "8": ["###", "#.#", "###", "#.#", "###"],
+    "9": ["###", "#.#", "###", "..#", "##."],
+    "!": ["#", "#", "#", ".", "#"],
+    "\"": ["#.#", "#.#", "...", "...", "..."],
+    "#": ["#.#", "###", "#.#", "###", "#.#"],
+    "$": [".#.", "###", "##.", ".##", "###"],
+    "%": ["#.#", "..#", ".#.", "#..", "#.#"],
+    "&": [".#.", "#.#", ".#.", "#.#", ".##"],
+    "'": ["#", "#", ".", ".", "."],
+    "(": [".#", "#.", "#.", "#.", ".#"],
+    ")": ["#.", ".#", ".#", ".#", "#."],
+    "*": ["...", "#.#", ".#.", "#.#", "..."],
+    "+": ["...", ".#.", "###", ".#.", "..."],
+    ",": ["..", "..", "..", ".#", "#."],
+    "-": ["...", "...", "###", "...", "..."],
+    ".": [".", ".", ".", ".", "#"],
+    "/": ["..#", "..#", ".#.", "#..", "#.."],
+    ":": [".", "#", ".", "#", "."],
+    ";": ["..", ".#", "..", ".#", "#."],
+    "<": ["..#", ".#.", "#..", ".#.", "..#"],
+    "=": ["...", "###", "...", "###", "..."],
+    ">": ["#..", ".#.", "..#", ".#.", "#.."],
+    "?": ["##.", "..#", ".#.", "...", ".#."],
+    "@": [".##", "#.#", "###", "#..", ".##"],
+    "[": ["##", "#.", "#.", "#.", "##"],
+    "\\": ["#..", "#..", ".#.", "..#", "..#"],
+    "]": ["##", ".#", ".#", ".#", "##"],
+    "^": [".#.", "#.#", "...", "...", "..."],
+    "_": ["...", "...", "...", "...", "###"],
+    "`": ["#.", ".#", "..", "..", ".."],
+    "{": [".##", ".#.", "##.", ".#.", ".##"],
+    "|": ["#", "#", "#", "#", "#"],
+    "}": ["##.", ".#.", ".##", ".#.", "##."],
+    "~": ["...", ".##", "##.", "...", "..."],
+    "°": [".#.", "#.#", ".#.", "...", "..."],
+    "±": [".#.", "###", ".#.", "...", "###"],
+    "×": ["...", "#.#", ".#.", "#.#", "..."],
+    "÷": [".#.", "...", "###", "...", ".#."],
+    "£": [".##", "#..", "##.", "#..", "###"],
+    "¥": ["#.#", "#.#", "###", ".#.", "###"],
+    "€": [".##", "#..", "###", "#..", ".##"],
+    "¢": [".#.", ".##", "#..", ".##", ".#."],
+    "•": ["..", "..", "##", "##", ".."],
+    "·": [".", ".", "#", ".", "."],
+    "←": [".#.", "#..", "###", "#..", ".#."],
+    "→": [".#.", "..#", "###", "..#", ".#."],
+    "↑": [".#.", "###", ".#.", ".#.", ".#."],
+    "↓": [".#.", ".#.", ".#.", "###", ".#."],
+    " ": {"rows": [], "advance": 2}
+  }
+}