Changelog

Copy Markdown View Source

v0.3.0 (2026-10-29)

Terms are the form (dco-tek/macaw/macaw#188). A value's identity and validity are the BEAM term's own; JSON, and every other encoding, is an adapter at the edge. This release is breaking throughout; the guide below is what an adopter of 0.2.4 changes, and the entries after it are the detail.

Upgrading from 0.2.4

  1. Digests change. Every digest is now over the value itself (Document.digest/1), so a stored digest, cache key or golden written by 0.2.4 differs. Regenerate them; nothing reads an old digest.
  2. Validity is judged on the value. A type's validate/1 receives the value (atom keys where the type has keys, string names, its own structs), never the map form. Judge a value built in Elixir with Document.check(value, type). Document.read/3 and Form.from_json/3 are gone: read untrusted JSON with Form.read(input, type, opts), whose gates (Form.gates/3) are the JSON adapter's.
  3. Name maps. A type whose maps hold names (a style named "fill") implements name_map?/1; a fragment type does it in one line with Fragment.name_map?/2. Names in a name map are strings; an atom there is {:type, :name} when written.
  4. Colors are terms. A literal color is %Color{} with float fields; a string is never a color. Write literals with ~RGB"#3b6fa8" in code and Color.parse!/1 at an edge, and write CSS with Color.to_css/1. Helpers raise for text and say so.
  5. A theme's names are strings, the theme's own name and its dark/light included (Theme.default().name == "default"). Atom input is still accepted at construction and normalized there, so most construction code is unchanged; code that matches on :default, :info or a slot atom in a theme's fields or in the lists it answers (slots/1, color_names/1, ramp_names/0, faults) matches strings now. A host's "info" now replaces the library's.
  6. Words are kept as given, and the JSON reader's vocabulary is the reader's: an extension that writes atoms of its own into styles or defaults implements Theme.Extension.words/0, and Theme.Document.from_json/2 is given extensions: to read them back.
  7. Theme JSON is version 2. A literal is tagged {"$rgb": "#hex"} and theme names are JSON strings. Version 1 documents written by 0.2.4 still read, through the version step, to the same theme; documents are written at version 2.
  8. The palette stacks through Theme.Style. Nothing changes for a theme without hooks; an adopter with its own style rules gives a fragment type through Theme.Extension.style_type/0.

Changes

Breaking: every digest changes.

  • The kernel's digest is over the value itself, any data term, not its map form (spec/01 §7, #3, macaw#188): a type-tagged canonical encoding of the term, so identity no longer needs a representation. 1/1.0, :a/"a", {:a}/[:a] and a DateTime's zone all count. A function, PID, reference, port or improper list raises.

Breaking: validity is judged on the value, and Form is the JSON adapter (spec/01 §5–§6, spec/03 §3.2–§3.3, spec/04 §5, #9, macaw#188).

  • Macaw.Layers.Document.validate/1 now receives the type's value (atom keys where the type has keys, string names, atoms, times, its own structs), never the map form. Document.check(value, type) judges a value with no encoding and no limits: how a value built in Elixir is judged. Document.read/3 is removed.
  • The gates move to the JSON adapter: Form.gates(input, type, opts) (bytes, scan, version, migration, recount, with limits: as before) gives the map form at the current version, and Form.read(input, type, opts) reads the value from it and checks it. The recount is now a gate of its own: its faults stop the read before the type's. Form.from_json/3 is removed (use Form.read/3); Form.to_json/2 stamps "$version" for a type with a version line.
  • Bundle.validate/1 judges a %Bundle{}; Bundle.check(bundle, types) adds each entry's kind. Bundle.from_map/3 and from_json/3 report the map form's own faults, then the entries' reads, then the term's check. Store.relocate/3 checks the bundle term instead of writing it to its map form and reading it back, so a bundle read under a raised limit relocates.
  • Theme.Document.from_map/2 judges the value with no form written or read and takes no limits: (they are from_json/2's); Theme.Document.validate/1 judges the envelope value, so a key beside theme is named by its atom.

The JSON adapter tells a name map from a node by the type's positions (spec/01 §6, spec/02 §9, spec/04 §5, #10, dco-tek/macaw/macaw#184).

  • An optional Form callback, name_map?(path): whether the map at path holds names, never the type's keys. At a name map a string key is written and read as the name, whatever its spelling (a style named "fill", a scale "x"), escaped as before when it starts with $; an atom key there is {:type, :name}, since names are strings. At a node, and for a type without the callback, keys are as before.
  • Fragment.name_map?(type, path), from the type's specs: a :union or :deep key holds a name map whose entries are nodes of its element kind, for a fragment type to implement the callback in one line.
  • Breaking: Theme.Document's ramps, colors, styles and defaults are name maps, and its value spells every name in them as a string: node/1, fragment/1 and to_map/1 write "info" where they wrote :info, so a theme entry of a store goes through a bundle's forms and import. Form.to_map/2 of a node with atom names is {:type, :name} at each. (#13, below, makes the theme itself hold strings, which retired the reading of a library spelling back as its atom.)
  • A use site's local is a fragment of the type: Form.encode_term/3 takes the term's place below its tag (at), the reader asks name_map?/1 at {:tag, tag} and the path within the payload, and Fragment.name_map?/2 places a $use local at the root's positions, so a local holding a style named "fill" round-trips.

Breaking: %Macaw.Layers.Color{} fields are floats (spec/04 §1.1, §1.6, #11, macaw#188).

  • A literal color is a term: every constructor (rgb, hsl, lab, hcl, oklab, oklch, parse, the manipulations and interpolations) builds %Color{} with every field a float, clamped, never a negative zero, so equal colors are one term and one digest whatever built them. hsl, lab and hcl still round their channels, now held as floats; interpolate_rgb/3 clamps its result. A struct written with integer fields still compares == but is not Color.literal?/1 and has another digest. to_rgb/1 and to_hex/1 are unchanged.
  • The adapters: Color.parse!/1 (raises ArgumentError naming the text) and the compile-time sigil ~RGB"#3b6fa8" (unreadable text is a CompileError) in; Color.to_css/1 out, hex where the color is 8-bit exact (Color.exact?/1), else rgb(r g b / a), which parse/1 now reads (CSS Color 4's space-separated rgb()).
  • Macaw.Layers.Color.Form is public, the colors' JSON adapter (tags/0, encode_value/1, decode_value/2), with the tag $rgb for a literal: the hex string when 8-bit exact, else [r, g, b, a]. A theme document's tag table lists it. (Text as a color goes in #12, below.)
  • Color.name?/1: the grammar of a theme's names (lower-case letters, digits and _, starting with a letter), the one its stylesheet names were already held to.

Breaking: a string is never a color; a theme holds color terms; theme JSON version 2 (spec/04 §1.3–§1.4, §2.1–§2.6, §3.1–§3.4, §4–§6, #12, macaw#188).

  • Color.value?/1 no longer accepts a string: a literal is %Color{} where Color.literal?/1 holds, so value?("#fff") is false, and a transform's operand is a color value, never text. The helpers (intensity/2, alpha/2, blend/1, contrast/1, shade/2, …) raise for text, naming Color.parse!/1 and ~RGB. saturate/2 of a literal keeps its HSL meaning; the transform of a literal is the tuple {:saturate, c, t}. Color.Form writes and reads operands and pinned steps in their own forms ($rgb), never bare strings.
  • %Theme{} holds terms: series and the furniture are literals, and so are the ramps' anchors, colors entries and pinned steps, transforms' operands and style paint colors where they are literal. The built-ins are written with ~RGB and resolve, compile and check exactly as before. Theme.new/1 and merge/2 raise for text in a color field (Theme.new(axis: "#555") raises naming Color.parse!/1 and ~RGB); text in a colors entry, a pinned step, an anchor or a style's fill/stroke color is a contract fault naming them; an extension's color default that is text raises naming the extension.
  • Theme.resolve(theme, slot, :literal), Color.resolve(v, theme, :literal), Theme.ramp/3, Theme.ink/2 and Theme.data_color/2's {:ok, c} answer %Color{}; :css writes each literal by Color.to_css/1, so every var() reference and the stylesheet are byte for byte as before. A transform's literal stays quantized to 8 bits. Theme.ink/2 takes a %Color{} or nil and raises for text. Theme.check_color/2 raises for a term that is no color value, text included; Theme.data_color/2 answers {:error, :unreadable} for text.
  • Theme.Document is at version 2: a literal is tagged $rgb. The step from version 1 tags each string at a color position that Color.parse/1 reads (the series, the furniture, ramp anchors, colors entries, $steps values, transform, $contrast and $blend operands, style fill/stroke colors), so a v0.2.4 document, and a bundle's entry of one, reads to the same theme; other text is refused at its path, a series entry or furniture as {:type, :color} (was {:type, :string}).
  • Removed: Color.Typed.unreadable/1 and readable?/1 (internal), whose only use was text as a color.

Breaking: a theme's names are strings, one key per spelling; words as given; the vocabulary is the JSON reader's (spec/04 §1.3, §1.6, §2.1–§2.6, §3.4, §5, spec/01 §5–§6, #13, macaw#188, macaw#181).

  • Every name inside %Theme{} is a string, the library's, its extensions' and a host's alike: the keys of ramps, colors, styles and defaults, the built-in palettes and colors, the slots and the name in every typed color ({:color, "good"}, {:ramp, "status", 0.5}). The lists answer strings: slots/1, color_slots/1, color_names/1 (now plainly sorted), style_names/1, ramp_names/0, role_names/0, series_slot/2, and check/1/violations/1 subjects ({:ramp, "status"}), floors/1 faults ({"text", …}, {"surface", {:equal, "grid"}}) and fault messages name them so. Every function that takes a name still takes either spelling.
  • Atom input is normalized once, at construction (Theme.new/1, merge/2, Theme.Document's read), by one function: colors: %{"info" => c} is the library's "info", the host's value winning — before, the library's :info silently shadowed a host's "info" (macaw#181) — and likewise a ramp "status" or a style "muted". A typed color's name normalizes wherever it stands (ramp anchors, colors entries, pinned steps, style nodes, defaults), so a ramp anchor {:color, :brand} is {:color, "brand"} and round-trips through JSON. One name given both as its atom and its string in one map raises ArgumentError; in a document value it is {:duplicate, :name} at [:theme, map, name].
  • Color.color/1 and Color.ramp/2 build the name's string (color(:red) is {:color, "red"}), and Color.Form reads $color and $ramp names as strings, never atoms: a typed color built in Elixir is the value its JSON form reads back.
  • Words are kept as given: Theme.new/1 no longer turns a style's or a default's keys and atom values outside the library's vocabulary into strings (curve: %{type: :monotone_x}, font: %{line_height: 1.2} stay atoms). Theme.Words holds only words now, no names.
  • The vocabulary is the JSON reader's: Form.read/3, from_map/3, to_map/3 and to_json/3 take vocabulary: %{keys: [...], atoms: [...]}, merged over the type's tables for that call; no atom is made from a document beyond them. Theme.Extension gains an optional words/0; Theme.Document.to_json/1 writes with the theme's extensions' words and from_json/2 reads with the extensions: given, so from_json needs extensions: for an adopter's words (without them an adopter's atom value is {:enum, allowed} at its path). An extension's styles/0 and colors/0 may name by atom or string; the theme holds them as strings.
  • Theme.Document's read path is the theme's normalization (its library-spelling-to-atom reading and the style-series name table are gone); Table.spelled/2's either-way search is gone, and Color.Names.atoms/0 (internal) is removed.

Breaking: a theme's own name and its dark and light are strings (spec/04 §2.1, §2.5, §5, #16).

  • %Theme{}'s name, dark and light are strings, the built-ins' included: Theme.default().name is "default" (was :default), default().dark "dark", dark().light "default", color_safe/0 and print/0 named "color_safe" and "print". Atom input is normalized once, at construction (new/1, merge/2, a document read), so new(name: :house) and new(name: "house") are one theme and new(dark: :dark) is new(dark: "dark"). Theme.builtin/1 takes either spelling (builtin("dark") == builtin(:dark)); Theme.builtins/0 (internal) answers strings. Fault messages name the theme as its string (theme "default": …).
  • Theme.Document writes the three as JSON strings ("dark": "dark", where it wrote {"$atom": "dark"}) and reads them as strings; a version 1 (v0.2.4) document's {"$atom": "dark"} migrates to "dark" in the step to version 2, and is refused at version 2; a name that is not a string is {:type, :string}. The stylesheet's theme classes are unchanged (.mw-theme-color-safe).

The palette stacks as a fragment type, and an adopter gives its style type (spec/04 §2.4, §3.4, spec/02 §3.3, #14, macaw#188, macaw#181).

  • Macaw.Layers.Theme.Style is a style node as a fragment type: root :style, every part %{merge: :override, node: :part}, no hooks. A list entry of the palette is Fragment.stack/2 of its layers, a left fold, in style/2, check/1 and violations/1 alike; for a theme with no extension's style type every entry is as before.
  • Theme.Extension gains an optional style_type/0: an adopter's fragment type of a style node with its own normalize/4 and under/3, which the theme stacks its palette with in place of Theme.Style (visualize D-172: a gradient over a solid paint drops its color). At most one extension per theme gives one; two raise ArgumentError naming both, and a module that is no fragment type raises naming the extension.

v0.2.4 (2026-10-29)

Additive: the hooks visualize needs to adopt the cascade and composites (macaw#179, macaw#183, visualize#963), and a load-order fix.

  • A host may raise a named limit, explicitly: Limits.new(items: {:raise, 500_000}), also through read/3's limits:; a plain value above the default still raises (spec/01 §5, #7, macaw#183).
  • The composite's hooks (spec/02 §8, #6, macaw#179): a type may scope/3 each site's contribution by the composite node's own keys (visualize's defaults), and place_whole/2 a keyed site's contribution of no kind under the site's key. spec/02 §8 says which keys a composite node holds.
  • The cascade's hooks (spec/02 §3.3, #5, macaw#179): a fragment type may normalize/4 a key both fragments hold (a shorthand against a part merges as the part) and trim with under/3 what of a lower node a higher one keeps (a node whose type changes); both hold in compose/3, stack/2 and explain/2. A trim is a replacement, so a stack where one happens is its left fold. explain/2 reports a normalized part's leaf with the layer that set it.
  • An optional callback is found whether or not its module is loaded: Macaw.Layers.Callback.exported?/3, used by Form, the cascade and every other site, replaces Fragment.callback?/3; CI refuses a bare function_exported?/3 (spec/01 §9, #4, macaw#136).

v0.2.3 (2026-10-28)

  • The macaw logo in the docs and the README (macaw#175).
  • Tests check "makes no atom" on the input's own names, never the node's atom count, and a test forbids the count (#1).

v0.2.2 (2026-10-28)

  • The README opens with the early-release notice (macaw#174).

v0.2.1 (2026-10-28)

  • Spec and README links to the public home, github.com/dcoai/macaw_layers, and the install snippet from Hex (macaw#171, #173).
  • Package metadata for Hex: the public home, the changelog link, the files shipped, and docs with ex_doc (macaw_compose#155).

v0.2.0 (2026-10-27)

  • macaw_layers v0.2.0: fragments and stacking, stores and bundles, colors and themes (macaw_compose#94)

v0.1.0 (2026-10-27)

  • macaw_layers v0.1.0: the document kernel (macaw_compose#56): names, vocabularies, faults, version lines, the gates, the forms and tags, the digest