glance-widgets-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1537f14e4b5207a0780552a0977c7e937b902f6e305996c8fc3887332569f234
+  data.tar.gz: 52d07498b2a230f9bc45e3a9a19fbb7b83b77d39f4fa407ca9374516f8e28ac4
+SHA512:
+  metadata.gz: de779835c49be6a9d0c3419946ef7e61b05555d0ec22bb3b16a09259eb98c952cb56393ca2539b3da1defe0f78d6ddcac1d510ccbc6b61b3dbd274367e03b015
+  data.tar.gz: bcf67db6eee7043ba6464ab7d30400be9b1d6c66ee533d8fc161a62d3048a61a4309bc73a587e7ef7f237cf3fb3d0fa842c906dcc761162fa2f442c38b81a074

data/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Glance Widgets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

data/README.md

@@ -0,0 +1,47 @@
+# Glance Widgets Ruby SDK
+
+SDK for generating Glance Widgets API responses
+
+Install from RubyGems:
+
+```sh
+gem install glance-widgets-sdk --version 1.0.0
+```
+
+Layer constructors return a `Composite`: `{layers, data}`. Declarations contain only id, type and dataPath; the addressed objects contain layout, content and style. Merge layer results and chart components with the same merge function, then finalize with toResponse (to_response in snake_case APIs). An explicit dataPath chooses the object location; otherwise it is derived from id.
+
+`Matrix.to_part()` returns `{content: MatrixData}`. Place it with `place` / `Place` to give its node a frame and data path. The node's `content` holds `pixels`, `default`, `batch` and `layout`; matrix `style` is empty. Image and image-backed icon nodes use `content.url`. Bind an editor layer to a partial node in `data` without adding a remote declaration. Omitted or null values keep the saved editor value; objects merge field by field, arrays replace, and a supplied frame replaces the whole frame and must include width and height. Each response starts from the saved configuration.
+
+Ruby 2.6+ implementation of the full protocol v1 SDK, using standard libraries. Install from this directory with `gem build glance_widgets.gemspec` and `gem install ./glance-widgets-sdk-1.0.0.gem`, or add `lib` to Ruby's load path.
+
+```ruby
+require 'glance_widgets'
+g = GlanceWidgets
+canvas = { 'width' => 338, 'height' => 158 }
+frame = g::Box.canvas(canvas).sub(0.1, 0.6, 0.8, 0.2).to_frame
+bar = g.pixel_progress_bar(65, 'canvas' => canvas, 'frame' => frame)
+response = g.to_response(g.place(bar, {
+  'id' => 'progress', 'frame' => frame, 'path' => 'data.progress'
+}))
+puts JSON.generate(response)
+```
+
+Use string keys for options and returned JSON objects. Protocol keys keep their camelCase spelling; Ruby methods use snake_case (`to_response`, `round_rect`, `flip_x`, `to_root`, `to_part`). Hash, Array and nil preserve JSON object, array and null values. Missing keys remain absent. Output hashes have deterministic insertion order.
+
+| TypeScript API | Ruby API |
+|---|---|
+| `Matrix`, drawing, text, transforms | `Matrix.new`, `round_rect`, `flood_fill`, `flip_x`, `rotate90`, etc. |
+| `Box.canvas`, `Box.fromFrame`, `Box.fromPt` | `Box.canvas`, `Box.from_frame`, `Box.from_pt` |
+| `merge`, `place`, `toResponse` | `merge`, `place`, `to_response` |
+| colors, fonts, themes, icons | `normalize_color`, `measure_text`, `get_theme`, `icon_glyph`, etc. |
+| geometry, pixelate, layer builders | `fit_matrix`, `solve_grid`, `pixelate`, `text`, `curve`, etc. |
+| validation and signatures | `validate`, `resolve_data_path`, `sign`, `verify_signature` |
+| semantic components | `bar_chart`, `line_chart`, `area_chart`, `sparkline`, `stat`, `progress_bar`, `ring_progress`, `battery`, `signal`, `pixel_bar_chart`, `pixel_progress_bar`, `pixel_ring_progress`, `status_strip`, `heatmap`, `calendar_heatmap`, `pixel_text_panel`, `pixel_text_root`, and `labeled_*` variants (`labeled_pixel_progress_bar`, `labeled_pixel_ring_progress`, ...) |
+
+Argument order and JSON options match TypeScript. Matrix drawing mutates the receiver; transforms return independent matrices. Builders return fragments, while `to_response` composes, completes and validates a response. `validate` returns nil or raises `GlanceValidationError` with a `path` reader. See the [guide](../../docs/guide.md) for the protocol and composition rules.
+
+Fonts, 5,287 icons, text advances and validator tables are bundled; loading the gem never reads repository files. Font and icon sources are `spec/fonts/*.json` and `spec/icons.json`. SF Pro widths come from `spec/tools/measure-text-advances.py`. The data-only `sdks/python/scripts/generate_data.py` extracts validation schema tables from TypeScript. Refresh these shared tables there when needed, then run `ruby sdks/ruby/scripts/sync-data.rb` to copy data into the gem. All Ruby algorithms are maintained directly in the modules under `lib/glance_widgets`.
+
+Run `bash integration/run-sdk-tests.sh ruby` from the repository. It checks every shared golden fixture plus native API tests for exact numeric labels, Unicode, validation, composition purity, clipping, and installation outside the repository. Golden numeric comparisons use relative tolerance `1e-9`; exact strings use exact comparison.
+
+Use `layer_path(id)` for the derived node path, and `validate_layer_node(node, type)` to validate a partial editor node before returning it.

data/lib/glance_widgets/box.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  class Box
+    attr_reader :left, :top, :width, :height
+
+    def initialize(left, top, width, height, canvas = nil)
+      unless [left, top, width, height].all? { |v| Numbers.finite?(v) } && width >= 0 && height >= 0
+        raise ArgumentError, 'Invalid Box geometry'
+      end
+      @left, @top, @width, @height, @canvas = left, top, width, height, DataValues.copy(canvas)
+    end
+
+    def self.canvas(canvas = nil)
+      new(0, 0, 1, 1, canvas)
+    end
+
+    def self.from_frame(frame, canvas)
+      from_pt(GlanceWidgets.resolve_frame(frame, canvas), canvas)
+    end
+
+    def self.from_pt(rect, canvas)
+      ratio = GlanceWidgets.to_ratio_rect(rect, canvas)
+      new(ratio['x'], ratio['y'], ratio['width'], ratio['height'], canvas)
+    end
+
+    def right
+      left + width
+    end
+
+    def bottom
+      top + height
+    end
+
+    def sub(x, y, w, h)
+      Box.new(left + x * width, top + y * height, w * width, h * height, @canvas)
+    end
+
+    def inset(value)
+      sides = insets(value)
+      sub(sides['left'], sides['top'], 1 - sides['left'] - sides['right'], 1 - sides['top'] - sides['bottom'])
+    end
+
+    def inset_pt(value)
+      rect, sides = to_pt, insets(value)
+      Box.from_pt({ 'x' => rect['x'] + sides['left'], 'y' => rect['y'] + sides['top'],
+                    'width' => [0, rect['width'] - sides['left'] - sides['right']].max,
+                    'height' => [0, rect['height'] - sides['top'] - sides['bottom']].max }, @canvas)
+    end
+
+    def rows(count_or_weights, options = {})
+      split('rows', count_or_weights, options)
+    end
+
+    def columns(count_or_weights, options = {})
+      split('columns', count_or_weights, options)
+    end
+
+    def split(direction, count_or_weights, options = {})
+      if count_or_weights.is_a?(Numeric)
+        unless Numbers.integer?(count_or_weights) && count_or_weights >= 0
+          raise ArgumentError, 'Invalid split count'
+        end
+        weights = Array.new(count_or_weights.to_i, 1)
+      else
+        weights = count_or_weights
+      end
+      unless weights.is_a?(Array) && !weights.empty? &&
+             weights.all? { |v| Numbers.finite?(v) && v >= 0 } && weights.inject(0) { |s, v| s + v } > 0
+        raise ArgumentError, 'Box.split needs non-negative weights with positive total'
+      end
+      vertical = direction == 'rows'
+      extent = vertical ? height : width
+      gap = DataValues.fetch_or(options, 'gap', 0) * extent
+      if DataValues.set?(options, 'gapPt')
+        canvas = GlanceWidgets.require_canvas(@canvas)
+        gap = options['gapPt'].fdiv(canvas[vertical ? 'height' : 'width'])
+      end
+      available = extent - gap * (weights.length - 1)
+      raise ArgumentError, 'Gaps are larger than the box' if available < 0
+      offset = vertical ? top : left
+      total = weights.inject(0) { |sum, weight| sum + weight }
+      weights.map do |weight|
+        size = (available * weight).fdiv(total)
+        box = vertical ? Box.new(left, offset, width, size, @canvas) : Box.new(offset, top, size, height, @canvas)
+        offset += size + gap
+        box
+      end
+    end
+
+    def to_pt
+      canvas = GlanceWidgets.require_canvas(@canvas)
+      { 'x' => left * canvas['width'], 'y' => top * canvas['height'],
+        'width' => width * canvas['width'], 'height' => height * canvas['height'] }
+    end
+
+    def to_frame
+      x, w = frame_axis(left, width)
+      y, h = frame_axis(top, height)
+      { 'left' => x, 'top' => y, 'width' => w, 'height' => h }
+    end
+
+    private
+
+    def insets(value)
+      %w[left top right bottom].each_with_object({}) do |key, sides|
+        sides[key] = value.is_a?(Hash) ? value.fetch(key, 0) : value
+      end
+    end
+
+    def frame_axis(start, size)
+      raise ArgumentError, 'Frame size exceeds 1.5' if size > 1.5
+      start, size = start + size / 2.0 - 0.01, 0.02 if size < 0.02
+      [start, size].map { |v| Numbers.round(v * 1e6) / 1e6 }
+    end
+  end
+end

data/lib/glance_widgets/color.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  COLOR_SPACE_CLASS = '[\u0009-\u000d\u0020\u00a0\u1680\u2000-\u200a' \
+                      '\u2028\u2029\u202f\u205f\u3000\ufeff]'
+  COLOR_WHITESPACE = Regexp.new("\\A#{COLOR_SPACE_CLASS}+|#{COLOR_SPACE_CLASS}+\\z")
+
+  def parse_color(color)
+    code = color.is_a?(String) ? color.gsub(COLOR_WHITESPACE, '') : nil
+    unless code && /\A#?(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})\z/i.match(code)
+      raise ArgumentError, 'Expected #RGB, #RRGGBB or #AARRGGBB'
+    end
+    code = code.sub(/\A#/, '')
+    code = code.chars.map { |char| char * 2 }.join if code.length == 3
+    code = 'FF' + code if code.length == 6
+    %w[a r g b].zip(code.scan(/../).map { |pair| pair.to_i(16) }).to_h
+  end
+
+  def format_color(color)
+    channels = %w[a r g b].map do |key|
+      Numbers.require_finite(color.fetch(key), 'Color channel')
+      '%02X' % Numbers.clamp(Numbers.round(color[key]), 0, 255)
+    end
+    '#' + (channels[0] == 'FF' ? channels[1..-1] : channels).join
+  end
+
+  def normalize_color(color)
+    format_color(parse_color(color))
+  end
+
+  def is_app_color(color)
+    color.is_a?(String) && !!/\A#?(?:[\da-f]{6}|[\da-f]{8})\z/i.match(color)
+  end
+
+  def rgb(red, green, blue, alpha = 1)
+    format_color('r' => red, 'g' => green, 'b' => blue, 'a' => alpha * 255)
+  end
+
+  def with_alpha(color, alpha)
+    format_color(parse_color(color).merge('a' => alpha * 255))
+  end
+
+  def mix_colors(start, finish, fraction)
+    a, b = parse_color(start), parse_color(finish)
+    fraction = Numbers.clamp(fraction, 0, 1)
+    format_color(a.each_with_object({}) { |(key, value), out| out[key] = value + (b[key] - value) * fraction })
+  end
+end

data/lib/glance_widgets/components/bar_chart.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  BAR_CHART_DEFAULTS = {
+    'id' => 'barChart', 'fontSizeRatio' => 0.06, 'barShareOfSlot' => 0.5, 'baselineWidth' => 1,
+    'baselineOpacity' => 0.3, 'labelOpacity' => 0.72, 'zIndex' => 0,
+    'colors' => MODERN_COLORS.merge('positive' => MODERN_COLORS['fill'], 'negative' => '#FF453A', 'baseline' => '#FFFFFF')
+  }.freeze
+
+  # Modern bar chart: one round-capped line layer per bar, a faint zero baseline and optional category labels.
+  def bar_chart(values, options)
+    raise ArgumentError, 'bar_chart: needs at least one value' if values.empty?
+    raise ArgumentError, 'bar_chart: values must be finite' unless values.all? { |v| Numbers.finite?(v) }
+    canvas = require_canvas(options['canvas'], 'bar_chart')
+    id, = Components.identity(options, 'barChart', 'bar_chart')
+    colors = BAR_CHART_DEFAULTS['colors'].merge(DataValues.fetch_or(options, 'colors', {}))
+    z = DataValues.fetch_or(options, 'zIndex', 0)
+    categories = DataValues.fetch_or(options, 'categories', [])
+    if !categories.empty? && categories.length != values.length
+      raise ArgumentError, 'bar_chart: categories must have one entry per value'
+    end
+    low = DataValues.fetch_or(options, 'min', [0, *values].min)
+    high = DataValues.fetch_or(options, 'max', [0, *values].max)
+    high = low + 1 if !DataValues.set?(options, 'min') && !DataValues.set?(options, 'max') && low == high
+    raise ArgumentError, "bar_chart: max (#{high}) must be greater than min (#{low})" unless high > low
+
+    ratio = DataValues.fetch_or(options, 'fontSizeRatio', 0.06)
+    pt = ratio * [canvas['width'], canvas['height']].min
+    area = Components.area(options['frame'], canvas).to_pt
+    label_row = categories.empty? ? 0 : pt * 0.4 + Components.text_height(pt)
+    plot_height = area['height'] - label_row
+    slot = area['width'].fdiv(values.length)
+    bar_width = DataValues.fetch_or(options, 'barWidth', [LINE_STROKE_MAX_PT, slot * 0.5].min)
+    Modern.require_stroke('bar_chart', 'barWidth', bar_width, LINE_STROKE_MAX_PT)
+    minimum = Modern.min_capsule_length(canvas, 'vertical', bar_width)
+    raise ArgumentError, 'bar_chart: the area is too short' unless plot_height > minimum
+
+    y_of = ->(v) { area['y'] + (1 - Components.fraction(v, low, high)) * plot_height }
+    zero = [high, [low, 0].max].min
+    base_y = y_of.call(zero)
+    layers = []
+    values.each_with_index do |value, index|
+      clamped = [high, [low, value].max].min
+      next if clamped == zero
+      value_y = y_of.call(clamped)
+      positive = clamped > zero
+      from, to = positive ? [[value_y, base_y - minimum].min, base_y] : [base_y, [value_y, base_y + minimum].max]
+      layers << Modern.capsule('id' => "#{id}:bar-#{index}", 'canvas' => canvas, 'direction' => 'vertical',
+                               'at' => area['x'] + (index + 0.5) * slot, 'from' => from, 'to' => to, 'width' => bar_width,
+                               'color' => positive ? colors['positive'] : colors['negative'], 'opacity' => 1, 'zIndex' => z)
+    end
+    if DataValues.fetch_or(options, 'showBaseline', true)
+      layers << horizontal_line('id' => id + ':baseline', 'at' => base_y / canvas['height'],
+                                'from' => area['x'] / canvas['width'], 'to' => (area['x'] + area['width']) / canvas['width'],
+                                'zIndex' => z,
+                                'style' => { 'color' => colors['baseline'], 'strokeWidth' => 1, 'opacity' => 0.3 })
+    end
+    categories.each_with_index do |category, index|
+      box = Box.from_pt({ 'x' => area['x'] + index * slot, 'y' => area['y'] + plot_height + pt * 0.4,
+                          'width' => slot, 'height' => Components.text_height(pt) }, canvas)
+      layers << Components.label("#{id}:category-#{index}", box, category, 'center', 'top', ratio, colors['label'], 0.72, z)
+    end
+    Components.combine(layers)
+  end
+end

data/lib/glance_widgets/components/battery.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  BATTERY_DEFAULTS = { 'id' => 'battery', 'min' => 0, 'max' => 100, 'height' => 12, 'widthRatio' => 2.3,
+                       'fontSizeRatio' => 0.07, 'zIndex' => 0 }.freeze
+  LABEL_GAP_EM = 0.4
+  BAD_LEVEL = 0.2
+  WARN_LEVEL = 0.4
+  BATTERY_HEIGHT_MIN_PT = 5
+  BATTERY_INSET_PT = 2
+  BATTERY_TAB_HEIGHT_RATIO = 0.5
+  BATTERY_TAB_WIDTH_RATIO = 0.25
+  BATTERY_TAB_GAP_PT = 1
+
+  # Modern battery: translucent capsule body, vertical capsule tab and a rounded level bar colored by charge.
+  def battery(level, options)
+    canvas = require_canvas(options['canvas'], 'battery')
+    id, = Components.identity(options, 'battery', 'battery')
+    minimum = options['min'].nil? ? 0 : options['min']
+    maximum = options['max'].nil? ? 100 : options['max']
+    Components.range('battery', minimum, maximum)
+    height = DataValues.fetch_or(options, 'height', BATTERY_DEFAULTS['height'])
+    unless height >= BATTERY_HEIGHT_MIN_PT && height <= CURVE_STROKE_MAX_PT
+      raise ArgumentError, "battery: height must be between #{BATTERY_HEIGHT_MIN_PT} and #{CURVE_STROKE_MAX_PT} pt, got #{height}"
+    end
+    colors = DataValues.fetch_or(options, 'colors', {})
+    z = DataValues.fetch_or(options, 'zIndex', 0)
+    fraction = Components.fraction(level, minimum, maximum)
+    track = DataValues.fetch_or(colors, 'track', MODERN_COLORS['track'])
+    status = fraction <= BAD_LEVEL ? 'bad' : (fraction <= WARN_LEVEL ? 'warn' : 'good')
+    level_color = DataValues.fetch_or(colors, 'fill', DataValues.fetch_or(colors, status, STATUS_COLORS[status]))
+    area = Components.area(options['frame'], canvas).to_pt
+    if area['height'] < height
+      raise ArgumentError, "battery: the area must be at least #{height} pt high, got #{area['height']}"
+    end
+    tab_width = height * BATTERY_TAB_WIDTH_RATIO
+    middle = area['y'] + area['height'] / 2.0
+
+    reserved = 0
+    label_layers = []
+    label = options['label']
+    unless label.nil? || label == false
+      content = label.is_a?(String) ? label : percent_label(fraction)
+      requested = Components.font_pt(DataValues.fetch_or(options, 'fontSizeRatio', 0.07), canvas)
+      pt = Components.font_pt(Components.font_ratio([requested, height / (TEXT_LINE_HEIGHT * LABEL_BOX_LINES)].min, canvas), canvas)
+      slot = Components.text_width(content, pt)
+      reserved = slot + pt * LABEL_GAP_EM
+      box = Box.from_pt({ 'x' => area['x'] + area['width'] - slot, 'y' => area['y'], 'width' => slot, 'height' => area['height'] }, canvas)
+      label_layers = [Components.label(id + ':label', box, content, 'right', 'center', Components.font_ratio(pt, canvas),
+                                       DataValues.fetch_or(colors, 'label', MODERN_COLORS['label']), 1, z + 1)]
+    end
+
+    available = area['width'] - reserved - BATTERY_TAB_GAP_PT - tab_width
+    body_width = [available, DataValues.fetch_or(options, 'width', height * BATTERY_DEFAULTS['widthRatio'])].min
+    unless body_width >= height + 0.1
+      raise ArgumentError, "battery: the area is too narrow (body #{body_width} pt)"
+    end
+    left = area['x']
+    spec = { 'canvas' => canvas, 'at' => middle, 'color' => track, 'opacity' => TRACK_OPACITY, 'zIndex' => z }
+    layers = [
+      Modern.curve_capsule(spec.merge('id' => id + ':body', 'from' => left, 'to' => left + body_width, 'width' => height)),
+      Modern.capsule(spec.merge('id' => id + ':tab', 'direction' => 'vertical',
+                                'at' => left + body_width + BATTERY_TAB_GAP_PT + tab_width / 2.0,
+                                'from' => middle - (height * BATTERY_TAB_HEIGHT_RATIO) / 2.0,
+                                'to' => middle + (height * BATTERY_TAB_HEIGHT_RATIO) / 2.0, 'width' => tab_width))
+    ]
+    thickness = height - 2 * BATTERY_INSET_PT
+    length = Modern.fill_length(fraction, body_width - 2 * BATTERY_INSET_PT, thickness)
+    if length > 0
+      layers << Modern.curve_capsule('canvas' => canvas, 'id' => id + ':level', 'from' => left + BATTERY_INSET_PT,
+                                     'to' => left + BATTERY_INSET_PT + length, 'at' => middle, 'width' => thickness,
+                                     'color' => level_color, 'opacity' => 1, 'zIndex' => z + 1)
+    end
+    layers.concat(label_layers)
+    Components.combine(layers)
+  end
+end

data/lib/glance_widgets/components/charts.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'pixel_bar_chart'
+require_relative 'bar_chart'
+require_relative 'line_chart'

data/lib/glance_widgets/components/heatmap.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  HEATMAP_DEFAULTS = { 'missing' => 'empty', 'calendarLevels' => 5 }.freeze
+  CALENDAR_HEATMAP_DEFAULTS = {
+    'startWeekday' => 0, 'orientation' => 'weekColumns',
+    'weekdayLabels' => %w[Sun Mon Tue Wed Thu Fri Sat],
+    'monthLabels' => %w[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec]
+  }.freeze
+  LABELED_CALENDAR_HEATMAP_DEFAULTS = {
+    'id' => 'calendar', 'fontSizeRatio' => 0.05, 'labelOpacity' => 0.72, 'zIndex' => 0
+  }.freeze
+
+  module Components
+    def heat_scale(values, theme, options, default_levels = nil)
+      stops = DataValues.fetch_or(options, 'scale', [theme['palette']['off'], theme['palette']['on']])
+      raise ArgumentError, 'Heat scale needs at least two colors' if stops.length < 2
+      levels = DataValues.fetch_or(options, 'levels', default_levels)
+      raise ArgumentError, 'Levels must be integer of at least 2' if levels && (!Numbers.integer?(levels) || levels < 2)
+      present = values.compact
+      present.each { |v| Numbers.require_finite(v, 'Heat value') }
+      minimum, maximum = DataValues.fetch_or(options, 'min', present.min || 0), DataValues.fetch_or(options, 'max', present.max || 0)
+      raise ArgumentError, 'Heat max must not be below min' if maximum < minimum
+      lambda do |value|
+        next nil if value.nil?
+        fraction = maximum > minimum ? Numbers.clamp((value - minimum).fdiv(maximum - minimum), 0, 1) : 0
+        fraction = [levels - 1, (fraction * levels).floor].min.fdiv(levels - 1) if levels
+        position = fraction * (stops.length - 1)
+        index = [stops.length - 2, position.floor].min
+        GlanceWidgets.mix_colors(stops[index], stops[index + 1], position - index)
+      end
+    end
+
+    def paint_heat(matrix, x, y, value, scale, missing)
+      color = scale.call(value)
+      matrix.set(x, y, color) if color
+      matrix.set(x, y, missing) if color.nil? && missing != EMPTY
+    end
+
+    def calendar_layout(count, options)
+      raise ArgumentError, 'Calendar needs at least one day' if count.zero?
+      weekday = DataValues.fetch_or(options, 'startWeekday', 0)
+      unless Numbers.integer?(weekday) && weekday.between?(0, 6)
+        raise ArgumentError, 'startWeekday must be 0..6'
+      end
+      weekday = weekday.to_i
+      orientation = DataValues.fetch_or(options, 'orientation', 'weekColumns')
+      raise ArgumentError, 'Invalid calendar orientation' unless %w[weekColumns weekRows].include?(orientation)
+      start = options['start']
+      unless start.is_a?(String) && /\A[0-9]{4}-[0-9]{2}-[0-9]{2}\z/.match(start)
+        raise ArgumentError, 'Calendar start must be YYYY-MM-DD'
+      end
+      year, month, day = start.split('-').map(&:to_i)
+      raise ArgumentError, 'Calendar year must be at least 100' if year < 100
+      beginning = Date.new(year, month, day, Date::GREGORIAN)
+      days = Array.new(count) { |i| beginning + i }
+      leading = (beginning.wday - weekday + 7) % 7
+      slots = Array.new(count) { |i| { 'week' => (leading + i) / 7, 'day' => (leading + i) % 7 } }
+      { 'days' => days, 'slots' => slots, 'weeks' => slots.last['week'] + 1,
+        'startWeekday' => weekday, 'vertical' => orientation == 'weekRows' }
+    end
+
+    def calendar_matrix(values, layout, options)
+      selected_theme = theme(options['theme'])
+      scale = heat_scale(values, selected_theme, options, 5)
+      vertical = layout['vertical']
+      size = { 'columns' => vertical ? 7 : layout['weeks'], 'rows' => vertical ? layout['weeks'] : 7 }
+      plan = grid(region(options, 'calendar_heatmap'), size, selected_theme, 'calendar_heatmap')
+      matrix = Matrix.new(plan['columns'], plan['rows'], GlanceWidgets.theme_options(
+        selected_theme, 'default' => EMPTY, 'layout' => plan['layout']
+      ))
+      values.zip(layout['slots']).each do |value, slot|
+        x, y = vertical ? [slot['day'], slot['week']] : [slot['week'], slot['day']]
+        paint_heat(matrix, x, y, value, scale, DataValues.fetch_or(options, 'missing', EMPTY))
+      end
+      matrix
+    end
+
+    def month_weeks(layout, minimum_gap)
+      labels = []
+      layout['days'].zip(layout['slots']).each do |day, slot|
+        if day.day == 1 && (labels.empty? || slot['week'] - labels.last['week'] >= minimum_gap)
+          labels << { 'week' => slot['week'], 'month' => day.month - 1 }
+        end
+      end
+      labels
+    end
+  end
+
+  def heatmap(values, options = {})
+    rows, columns = values.length, values.empty? ? 0 : values.first.length
+    unless rows > 0 && columns > 0 && values.all? { |row| row.length == columns }
+      raise ArgumentError, 'Heatmap needs non-empty rectangular grid'
+    end
+    theme = Components.theme(options['theme'])
+    scale = Components.heat_scale(values.flatten, theme, options)
+    size = { 'columns' => columns, 'rows' => rows }
+    plan = Components.grid(Components.region(options, 'heatmap'), size, theme, 'heatmap')
+    matrix_options = theme_options(theme, 'default' => EMPTY, 'layout' => plan['layout'])
+    matrix = Matrix.new(plan['columns'], plan['rows'], matrix_options)
+    values.each_with_index do |row, y|
+      row.each_with_index do |value, x|
+        Components.paint_heat(matrix, x, y, value, scale, DataValues.fetch_or(options, 'missing', EMPTY))
+      end
+    end
+    matrix.to_part
+  end
+
+  def calendar_heatmap(days, options)
+    Components.calendar_matrix(days, Components.calendar_layout(days.length, options), options).to_part
+  end
+
+  def labeled_calendar_heatmap(days, options)
+    canvas = require_canvas(options['canvas'], 'labeled_calendar_heatmap')
+    id, path = Components.identity(options, 'calendar', 'labeled_calendar_heatmap')
+    theme = Components.theme(options['theme'])
+    layout = Components.calendar_layout(days.length, options)
+    weekdays = DataValues.fetch_or(options, 'weekdayLabels', CALENDAR_HEATMAP_DEFAULTS['weekdayLabels'])
+    months = DataValues.fetch_or(options, 'monthLabels', CALENDAR_HEATMAP_DEFAULTS['monthLabels'])
+    unless weekdays.length == 7 && months.length == 12
+      raise ArgumentError, 'Calendar requires 7 weekday and 12 month names'
+    end
+    show_days, show_months = DataValues.fetch_or(options, 'showWeekdayLabels', true), DataValues.fetch_or(options, 'showMonthLabels', true)
+    z, ratio = DataValues.fetch_or(options, 'zIndex', 0), DataValues.fetch_or(options, 'fontSizeRatio', 0.05)
+    pt = Components.font_pt(ratio, canvas)
+    row_pt, gap_pt = pt * 1.2 * 1.3, pt * 0.4
+    widest = ->(names) { names.map { |name| Components.text_width(name, pt) }.max }
+    vertical = layout['vertical']
+    side_reserve = (show_days && !vertical ? widest.call(weekdays) : 0) +
+                   (show_months && vertical ? widest.call(months) : 0)
+    top_reserve = (show_days && vertical) || (show_months && !vertical) ? row_pt : 0
+    area = Components.area(options['frame'], canvas)
+    rect = area.to_pt
+    grid_box = area.inset_pt('left' => side_reserve > 0 ? side_reserve + gap_pt : 0,
+                            'top' => top_reserve > 0 ? top_reserve + gap_pt : 0)
+    grid = Components.emitted(grid_box, canvas)
+    matrix = Components.calendar_matrix(days, layout, options.merge('frame' => grid_box, 'canvas' => canvas))
+    placed = place(matrix.to_part, 'id' => id + ':grid', 'frame' => grid['frame'], 'path' => path, 'zIndex' => z)
+    geometry = fit_matrix(grid['rect'], { 'columns' => matrix.columns, 'rows' => matrix.rows }, matrix.layout)
+    layers = [placed]
+    label_color = DataValues.fetch_or(DataValues.fetch_or(options, 'colors', {}), 'label', theme['palette']['on'])
+    add = lambda do |role, label_rect, content, horizontal|
+      layers << Components.label(id + ':' + role, Box.from_pt(label_rect, canvas), content, horizontal, 'center',
+                                  ratio, label_color, 0.72, z + 1)
+    end
+    left = ->(x, width) { [rect['x'], [x, rect['x'] + rect['width'] - width].min].max }
+    top = ->(y, height) { [rect['y'], [y, rect['y'] + rect['height'] - height].min].max }
+    if show_days
+      [1, 3, 5].each do |day|
+        name = weekdays[(layout['startWeekday'] + day) % 7]
+        width = Components.text_width(name, pt)
+        cell = vertical ? cell_rect(geometry, day, 0) : cell_rect(geometry, 0, day)
+        label_rect = if vertical
+                       { 'x' => left.call(cell['x'] + cell['width'] / 2 - width / 2, width), 'y' => rect['y'],
+                         'width' => width, 'height' => row_pt }
+                     else
+                       { 'x' => rect['x'], 'y' => top.call(cell['y'] + cell['height'] / 2 - row_pt / 2, row_pt),
+                         'width' => widest.call(weekdays), 'height' => row_pt }
+                     end
+        add.call("weekday-#{day}", label_rect, name, vertical ? 'center' : 'right')
+      end
+    end
+    if show_months
+      pitch = vertical ? geometry['cellHeight'] + geometry['gapY'] : geometry['cellWidth'] + geometry['gapX']
+      minimum_gap = [1, Numbers.ceil((vertical ? row_pt : widest.call(months)) / pitch)].max
+      labels = Components.month_weeks(layout, minimum_gap)
+      labels.each do |label|
+        week, month = label['week'], label['month']
+        name = months[month]
+        if vertical
+          cell = cell_rect(geometry, 0, week)
+          label_rect = { 'x' => rect['x'], 'y' => top.call(cell['y'] + cell['height'] / 2 - row_pt / 2, row_pt),
+                         'width' => widest.call(months), 'height' => row_pt }
+        else
+          cell = cell_rect(geometry, week, 0)
+          width = Components.text_width(name, pt)
+          label_rect = { 'x' => left.call(cell['x'], width), 'y' => rect['y'], 'width' => width, 'height' => row_pt }
+        end
+        add.call("month-#{week}", label_rect, name, vertical ? 'right' : 'left')
+      end
+    end
+    Components.combine(layers)
+  end
+end