etassia 0.1.0

data/lib/etassia/theme/builtin/light.yml

@@ -0,0 +1,229 @@
+name: light
+description: "Light theme with softer colors"
+
+colors:
+  background: "#fafafa"
+  surface: "#ffffff"
+  surface_variant: "#f0f0f0"
+
+  foreground: "#333333"
+  foreground_secondary: "#757575"
+
+  primary: "#1976d2"
+  secondary: "#757575"
+  accent: "#388e3c"
+  error: "#d32f2f"
+  warning: "#f57c00"
+  success: "#388e3c"
+  info: "#0288d1"
+
+  node_fill: "#ffffff"
+  node_stroke: "#757575"
+  edge_stroke: "#757575"
+  label_text: "#333333"
+
+  hover_fill: "#f5f5f5"
+  active_fill: "#eeeeee"
+  disabled_fill: "#e0e0e0"
+
+  # Colours renderers drew from a hardcoded fallback; same in every theme.
+  architecture_group_border: "#999"
+  architecture_group_label: "#333"
+  border: "#d1d5db"
+  edge_color: "#666"
+  field_background: "#efefef"
+  field_border: "#000000"
+  field_text: "#000000"
+  group_background: "#f0f0f0"
+  highlight: "#fbbf24"
+  node_bg: "#E3F2FD"
+  node_text: "#FFFFFF"
+  note_fill: "#fefecd"
+  quadrant_grid_line: "#c7c7f1"
+  radar_axis_line: "#9ca3af"
+  radar_grid_line: "#e5e7eb"
+  requirement_box_border: "#333"
+  requirement_detail_text: "#666"
+  requirement_element_border: "#00796b"
+  requirement_text: "#000"
+  requirement_unknown_risk_border: "#666"
+  section_bg: "#f0f0f0"
+  title_text: "#000000"
+  card_text: "#1f2937"
+  xy_axis_line: "#000000"
+  xy_grid_line: "#e5e7eb"
+
+  # Categorical palettes are indexed modulo length.
+  flow_palette:
+    - "#4472C4"
+    - "#ED7D31"
+    - "#A5A5A5"
+    - "#FFC000"
+    - "#5B9BD5"
+    - "#70AD47"
+    - "#C00000"
+    - "#7030A0"
+  git_graph_palette:
+    - "#2563eb"
+    - "#7c3aed"
+    - "#db2777"
+    - "#ea580c"
+    - "#ca8a04"
+    - "#16a34a"
+    - "#0891b2"
+    - "#4f46e5"
+    - "#c026d3"
+    - "#dc2626"
+  mindmap_palette:
+    - "#1976d2"
+    - "#757575"
+    - "#388e3c"
+    - "#ea580c"
+    - "#16a34a"
+    - "#0891b2"
+  pie_palette:
+    - "#4472C4"
+    - "#ED7D31"
+    - "#A5A5A5"
+    - "#FFC000"
+    - "#5B9BD5"
+    - "#70AD47"
+    - "#264478"
+    - "#9E480E"
+    - "#636363"
+    - "#997300"
+    - "#255E91"
+    - "#43682B"
+  radar_palette:
+    - "#2563eb"
+    - "#7c3aed"
+    - "#db2777"
+    - "#ea580c"
+    - "#ca8a04"
+    - "#16a34a"
+    - "#0891b2"
+    - "#4f46e5"
+    - "#c026d3"
+    - "#dc2626"
+  quadrant_palette:
+    - "#ECECFF"
+    - "#f1f1ff"
+    - "#f6f6ff"
+    - "#fbfbff"
+  requirement_risk_palette:
+    - "#ff6b6b"
+    - "#ffd93d"
+    - "#6bcf7f"
+  xy_palette:
+    - "#2563eb"
+    - "#7c3aed"
+    - "#db2777"
+    - "#ea580c"
+    - "#ca8a04"
+    - "#16a34a"
+    - "#0891b2"
+    - "#4f46e5"
+    - "#c026d3"
+    - "#dc2626"
+  timeline_fill_palette:
+    - "#8686ff"
+    - "#ffff78"
+    - "#d7ff86"
+    - "#c286ff"
+    - "#ff86ff"
+    - "#ff86c2"
+    - "#ff8686"
+    - "#ffc286"
+    - "#c2ff86"
+    - "#86ffc2"
+    - "#86ffff"
+    - "#86c2ff"
+  timeline_text_palette:
+    - "#ffffff"
+    - "#000000"
+    - "#000000"
+    - "#ffffff"
+    - "#000000"
+    - "#000000"
+    - "#000000"
+    - "#000000"
+    - "#000000"
+    - "#000000"
+    - "#000000"
+    - "#000000"
+  timeline_rule_palette:
+    - "#ffffb9"
+    - "#ababff"
+    - "#d0b9ff"
+    - "#dcffb9"
+    - "#b9ffb9"
+    - "#b9ffdc"
+    - "#b9ffff"
+    - "#b9dcff"
+    - "#dcb9ff"
+    - "#ffb9dc"
+    - "#ffb9b9"
+    - "#ffdcb9"
+  treemap_palette:
+    - "#8dd3c7"
+    - "#ffffb3"
+    - "#bebada"
+    - "#fb8072"
+  user_journey_actor_palette:
+    - "#8FBC8F"
+    - "#7CFC00"
+    - "#00FFFF"
+    - "#20B2AA"
+    - "#B0E0E6"
+    - "#FFFFE0"
+  user_journey_section_palette:
+    - "#191970"
+    - "#8B008B"
+    - "#4B0082"
+    - "#2F4F4F"
+    - "#800000"
+    - "#8B4513"
+    - "#00008B"
+
+typography:
+  font_family: "Arial, Helvetica, sans-serif"
+  font_family_monospace: "Courier New, monospace"
+  font_size_small: 12.0
+  font_size_normal: 14.0
+  font_size_large: 16.0
+  font_size_title: 20.0
+  font_weight_normal: "normal"
+  font_weight_bold: "bold"
+  line_height: 1.5
+  text_transform: "none"
+
+shapes:
+  stroke_width: 1.5
+  stroke_width_thick: 2.5
+  stroke_width_thin: 1.0
+  fill_opacity: 1.0
+  stroke_opacity: 1.0
+  corner_radius: 4.0
+  corner_radius_large: 8.0
+  dash_pattern_dotted: "2,2"
+  dash_pattern_dashed: "5,5"
+
+spacing:
+  node_padding_x: 12.0
+  node_padding_y: 6.0
+  node_margin: 20.0
+  edge_spacing: 10.0
+  edge_label_offset: 5.0
+  rank_spacing: 100.0
+  node_spacing: 50.0
+
+effects:
+  shadow_enabled: false
+  shadow_color: "#00000033"
+  shadow_blur: 4.0
+  shadow_offset_x: 2.0
+  shadow_offset_y: 2.0
+  gradient_enabled: false
+  gradient_type: "linear"
+  arrow_size: 10.0
+  arrow_style: "filled"

data/lib/etassia/theme/color_palette.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+raise NameError, "uninitialized constant Etassia::Theme" unless defined?(Etassia::Theme)
+
+# Represents the color palette for diagram theming
+module Etassia
+  class Theme
+    class ColorPalette < Lutaml::Model::Serializable
+      attribute :background, :string
+      attribute :surface, :string
+      attribute :surface_variant, :string
+      attribute :foreground, :string
+      attribute :foreground_secondary, :string
+      attribute :primary, :string
+      attribute :secondary, :string
+      attribute :accent, :string
+      attribute :error, :string
+      attribute :warning, :string
+      attribute :success, :string
+      attribute :info, :string
+      attribute :node_fill, :string
+      attribute :node_stroke, :string
+      attribute :edge_stroke, :string
+      attribute :label_text, :string
+      attribute :hover_fill, :string
+      attribute :active_fill, :string
+      attribute :disabled_fill, :string
+
+      EXTRA_COLORS = %i[
+        architecture_group_border architecture_group_label border edge_color
+        field_background field_border field_text group_background highlight
+        node_bg node_text note_fill quadrant_grid_line radar_axis_line
+        radar_grid_line requirement_box_border requirement_detail_text
+        requirement_element_border requirement_text
+        requirement_unknown_risk_border section_bg title_text card_text
+        xy_axis_line xy_grid_line
+      ].freeze
+
+      EXTRA_COLORS.each { |name| attribute name, :string }
+
+      PALETTES = %i[
+        flow git_graph mindmap pie quadrant radar requirement_risk timeline_fill
+        timeline_text timeline_rule treemap user_journey_actor
+        user_journey_section xy
+      ].freeze
+
+      PALETTES.each do |name|
+        attribute :"#{name}_palette", :string, collection: true
+      end
+
+      yaml do
+        map "background", to: :background
+        map "surface", to: :surface
+        map "surface_variant", to: :surface_variant
+        map "foreground", to: :foreground
+        map "foreground_secondary", to: :foreground_secondary
+        map "primary", to: :primary
+        map "secondary", to: :secondary
+        map "accent", to: :accent
+        map "error", to: :error
+        map "warning", to: :warning
+        map "success", to: :success
+        map "info", to: :info
+        map "node_fill", to: :node_fill
+        map "node_stroke", to: :node_stroke
+        map "edge_stroke", to: :edge_stroke
+        map "label_text", to: :label_text
+        map "hover_fill", to: :hover_fill
+        map "active_fill", to: :active_fill
+        map "disabled_fill", to: :disabled_fill
+        EXTRA_COLORS.each { |name| map name.to_s, to: name }
+        PALETTES.each { |name| map "#{name}_palette", to: :"#{name}_palette" }
+      end
+
+      # Picks a colour from a named categorical palette, wrapping past the end.
+      #
+      # @param name [Symbol] one of PALETTES
+      # @param index [Integer] position, counted from 0
+      # @return [String] the colour
+      # @raise [KeyError] when the name is unknown or the theme lacks it
+      def palette(name, index)
+        unless PALETTES.include?(name)
+          raise KeyError, "unknown palette: #{name.inspect}"
+        end
+
+        colours = public_send(:"#{name}_palette")
+        if colours.nil? || colours.empty?
+          raise KeyError, "theme defines no #{name} palette"
+        end
+
+        colours.fetch(index % colours.length)
+      end
+    end
+  end
+end

data/lib/etassia/theme/completion.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../theme"
+require_relative "registry"
+
+module Etassia
+  class Theme
+    # Fills the categorical palettes a theme leaves unset from the default
+    # theme: a chart cannot pick series colours from an empty list. Single
+    # colours stay as given, so a theme that names no colour for something
+    # still draws it unpainted.
+    module Completion
+      PALETTE_KEYS = ColorPalette::PALETTES.map do |name|
+        :"#{name}_palette"
+      end.freeze
+
+      module_function
+
+      # @param theme [Theme, nil] the caller's theme, possibly partial
+      # @param base [Theme, nil] where unset palettes come from
+      # @return [Theme, nil] the theme itself when every palette is set,
+      #   otherwise a filled copy; the caller's theme is never modified
+      def call(theme, base = Registry.get(:default))
+        return base if theme.nil?
+        return theme if base.nil? || complete?(theme.colors)
+
+        completed = theme.dup
+        completed.colors = filled_colors(theme.colors, base.colors)
+        completed
+      end
+
+      def complete?(colors)
+        PALETTE_KEYS.all? { |key| set_value(colors&.public_send(key)) }
+      end
+
+      def filled_colors(colors, defaults)
+        values = ColorPalette.attributes.keys.to_h do |key|
+          given = set_value(colors&.public_send(key))
+          fill = PALETTE_KEYS.include?(key) && defaults.public_send(key)
+          [key, given || fill || nil]
+        end
+        ColorPalette.new(**values)
+      end
+
+      def set_value(value)
+        value unless value.respond_to?(:empty?) && value.empty?
+      end
+    end
+  end
+end

data/lib/etassia/theme/effect_styles.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+raise NameError, "uninitialized constant Etassia::Theme" unless defined?(Etassia::Theme)
+
+# Represents effect styles for diagram theming
+module Etassia
+  class Theme
+    class EffectStyles < Lutaml::Model::Serializable
+      attribute :shadow_enabled, :boolean
+      attribute :shadow_color, :string
+      attribute :shadow_blur, :float
+      attribute :shadow_offset_x, :float
+      attribute :shadow_offset_y, :float
+      attribute :gradient_enabled, :boolean
+      attribute :gradient_type, :string
+      attribute :arrow_size, :float
+      attribute :arrow_style, :string
+
+      yaml do
+        map "shadow_enabled", to: :shadow_enabled
+        map "shadow_color", to: :shadow_color
+        map "shadow_blur", to: :shadow_blur
+        map "shadow_offset_x", to: :shadow_offset_x
+        map "shadow_offset_y", to: :shadow_offset_y
+        map "gradient_enabled", to: :gradient_enabled
+        map "gradient_type", to: :gradient_type
+        map "arrow_size", to: :arrow_size
+        map "arrow_style", to: :arrow_style
+      end
+    end
+  end
+end

data/lib/etassia/theme/registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../theme"
+
+# Registry for pre-defined and custom themes
+module Etassia
+  class Theme
+    class Registry
+      @themes = {}
+
+      class << self
+        # Register a theme
+        def register(name, theme)
+          @themes[name.to_sym] = theme
+        end
+
+        # Get a theme by name
+        def get(name)
+          @themes[name.to_sym]
+        end
+
+        # List all registered theme names
+        def list
+          @themes.keys
+        end
+
+        # Load all built-in themes
+        def load_builtin_themes
+          builtin_dir = File.join(__dir__, "builtin")
+          return unless Dir.exist?(builtin_dir)
+
+          Dir.glob(File.join(builtin_dir, "*.yml")).each do |path|
+            theme = Etassia::Theme.load(path)
+            register(theme.name, theme)
+          end
+        end
+
+        # Clear all registered themes (useful for testing)
+        def clear
+          @themes = {}
+        end
+      end
+    end
+  end
+end

data/lib/etassia/theme/shape_styles.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+raise NameError, "uninitialized constant Etassia::Theme" unless defined?(Etassia::Theme)
+
+# Represents shape styling settings for diagram theming
+module Etassia
+  class Theme
+    class ShapeStyles < Lutaml::Model::Serializable
+      attribute :stroke_width, :float
+      attribute :stroke_width_thick, :float
+      attribute :stroke_width_thin, :float
+      attribute :fill_opacity, :float
+      attribute :stroke_opacity, :float
+      attribute :corner_radius, :float
+      attribute :corner_radius_large, :float
+      attribute :dash_pattern_dotted, :string
+      attribute :dash_pattern_dashed, :string
+
+      yaml do
+        map "stroke_width", to: :stroke_width
+        map "stroke_width_thick", to: :stroke_width_thick
+        map "stroke_width_thin", to: :stroke_width_thin
+        map "fill_opacity", to: :fill_opacity
+        map "stroke_opacity", to: :stroke_opacity
+        map "corner_radius", to: :corner_radius
+        map "corner_radius_large", to: :corner_radius_large
+        map "dash_pattern_dotted", to: :dash_pattern_dotted
+        map "dash_pattern_dashed", to: :dash_pattern_dashed
+      end
+    end
+  end
+end

data/lib/etassia/theme/spacing_config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+raise NameError, "uninitialized constant Etassia::Theme" unless defined?(Etassia::Theme)
+
+# Represents spacing configuration for diagram theming
+module Etassia
+  class Theme
+    class SpacingConfig < Lutaml::Model::Serializable
+      attribute :node_padding_x, :float
+      attribute :node_padding_y, :float
+      attribute :node_margin, :float
+      attribute :edge_spacing, :float
+      attribute :edge_label_offset, :float
+      attribute :rank_spacing, :float
+      attribute :node_spacing, :float
+
+      yaml do
+        map "node_padding_x", to: :node_padding_x
+        map "node_padding_y", to: :node_padding_y
+        map "node_margin", to: :node_margin
+        map "edge_spacing", to: :edge_spacing
+        map "edge_label_offset", to: :edge_label_offset
+        map "rank_spacing", to: :rank_spacing
+        map "node_spacing", to: :node_spacing
+      end
+    end
+  end
+end

data/lib/etassia/theme/typography.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+raise NameError, "uninitialized constant Etassia::Theme" unless defined?(Etassia::Theme)
+
+# Represents typography settings for diagram theming
+module Etassia
+  class Theme
+    class Typography < Lutaml::Model::Serializable
+      attribute :font_family, :string
+      attribute :font_family_monospace, :string
+      attribute :font_size_small, :float
+      attribute :font_size_normal, :float
+      attribute :font_size_large, :float
+      attribute :font_size_title, :float
+      attribute :sequence_font_size, :float
+      attribute :flowchart_font_size, :float
+      attribute :font_weight_normal, :string
+      attribute :font_weight_bold, :string
+      attribute :line_height, :float
+      attribute :text_transform, :string
+
+      yaml do
+        map "font_family", to: :font_family
+        map "font_family_monospace", to: :font_family_monospace
+        map "font_size_small", to: :font_size_small
+        map "font_size_normal", to: :font_size_normal
+        map "font_size_large", to: :font_size_large
+        map "font_size_title", to: :font_size_title
+        map "sequence_font_size", to: :sequence_font_size
+        map "flowchart_font_size", to: :flowchart_font_size
+        map "font_weight_normal", to: :font_weight_normal
+        map "font_weight_bold", to: :font_weight_bold
+        map "line_height", to: :line_height
+        map "text_transform", to: :text_transform
+      end
+    end
+  end
+end

data/lib/etassia/theme.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  # Theme's real attributes are defined once, here. The requires below sit
+  # inside this class body rather than above it: Ruby binds the `Theme`
+  # constant before running the body, so by the time they execute,
+  # Etassia::Theme already exists for the five sub-model files (each written
+  # compact-style, e.g. `class Etassia::Theme::Typography`) to be defined
+  # under. A sub-model file required standalone (bypassing this file) would
+  # raise NameError on Etassia::Theme, not resolve to a wrong superclass.
+  class Theme < Lutaml::Model::Serializable
+    MERGEABLE_ATTRIBUTES = %i[colors typography shapes spacing effects].freeze
+
+    require_relative "theme/color_palette"
+    require_relative "theme/typography"
+    require_relative "theme/shape_styles"
+    require_relative "theme/spacing_config"
+    require_relative "theme/effect_styles"
+
+    attribute :name, :string
+    attribute :description, :string
+    attribute :colors, ColorPalette
+    attribute :typography, Typography
+    attribute :shapes, ShapeStyles
+    attribute :spacing, SpacingConfig
+    attribute :effects, EffectStyles
+
+    yaml do
+      map "name", to: :name
+      map "description", to: :description
+      map "colors", to: :colors
+      map "typography", to: :typography
+      map "shapes", to: :shapes
+      map "spacing", to: :spacing
+      map "effects", to: :effects
+    end
+
+    # Load theme from YAML file
+    def self.load(path)
+      yaml_content = File.read(path)
+      from_yaml(yaml_content)
+    end
+
+    # Merge with another theme (for overrides)
+    def merge(other_theme)
+      self.class.new(
+        name: other_theme.name || name,
+        description: other_theme.description || description,
+        **merged_attributes(other_theme),
+      )
+    end
+
+    private
+
+    def merged_attributes(other_theme)
+      MERGEABLE_ATTRIBUTES.to_h do |attribute|
+        values = [public_send(attribute), other_theme.public_send(attribute)]
+        [attribute, merge_attribute(*values)]
+      end
+    end
+
+    def merge_attribute(base, override)
+      return base if override.nil?
+      return override if base.nil?
+
+      # For now, just use override if provided, base otherwise
+      # Full deep merge would require iterating over attributes
+      override
+    end
+  end
+end

data/lib/etassia/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Etassia
+  VERSION = "0.1.0"
+end

data/lib/etassia.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "etassia/version"
+require_relative "etassia/error"
+require_relative "etassia/error_report"
+require_relative "etassia/runtime"
+
+module Etassia
+  # Faults a hostile DOCUMENT can provoke that are not `StandardError`, so
+  # every ordinary rescue in this gem -- and in any host embedding it --
+  # lets them past and the process goes down.
+  # Derived rather than collected a name at a time: every `Exception`
+  # descendant loaded in this process that is not a `StandardError` was
+  # enumerated and classified, and exactly these two are exhaustion caused
+  # by the source being rendered. The rest are Ruby's own control flow
+  # (`SystemExit`, `SignalException`, `Timeout::ExitException`, `fatal`),
+  # a broken install (`ScriptError` and its subclasses), or `SecurityError`
+  # -- none of which mean "this diagram failed to render", and three of
+  # which MUST reach the caller or `exit`, Ctrl-C and a host's
+  # `Timeout.timeout` stop working. That is why this is an allowlist of two
+  # and not a `rescue Exception` with a list of exemptions.
+  #
+  # `spec/etassia/engine_exhaustion_errors_spec.rb` enumerates the
+  # loaded hierarchy
+  # and holds this list against it in the two directions a machine can
+  # decide: every name here really is outside `StandardError`, and no
+  # control-flow class is here. Whether a NEW class is exhaustion is a
+  # judgement Ruby exposes no marker for, so no spec can make that call --
+  # adding one to this list is a human decision, taken here.
+  EXHAUSTION_ERRORS = [SystemStackError, NoMemoryError].freeze
+
+  # Convenience method for rendering diagrams to SVG
+  #
+  # @param source [String] diagram source code
+  # @param options [Hash] Rendering options, see {Engine#render}
+  # @return [String] SVG output
+  # @see Runtime for the optional Rust runtime (ETASSIA_RUNTIME)
+  def self.render(source, options = {}) = Runtime.or_ruby(source, options)
+end
+require_relative "etassia/notation/builtin"