Class: DocsKit::BrandLogo

Inherits:
Object
  • Object
show all
Defined in:
lib/docs_kit/brand_logo.rb

Overview

The normalized brand mark for the shell chrome (config.brand_logo) and the landing hero (config.landing.logo). A site configures a Hash in exactly one of five forms; DocsUI::Logo renders the result:

{ svg: "M0 0Z", viewbox: "0 0 24 24", label: "Acme" }   # one path-d (landing-compat)
{ paths: ["M0 0Z", "M4 4Z"], viewbox: "…", label: "…" } # multi-path wordmark
{ markup: "<svg …>…</svg>", label: "Acme" }             # raw SVG markup, embedded verbatim
{ file: "app/assets/images/mark.svg", label: "Acme" }   # a .svg file, embedded inline
{ src: "logo.png", alt: "Acme" }                        # an <img> (not theme-adaptive)

The svg:/paths: forms render each d as an ordinary Phlex-escaped attribute. The markup:/file: forms embed SITE-AUTHORED markup verbatim (see DocsUI::Logo for the trust rationale); both are shape-checked here — the content must be an element — so a mis-pasted snippet fails loudly at config time, never as a silently broken (or script-bearing) header. Mixing forms, or giving none, is ambiguous config and raises. label/alt fall back to each other so either knob names the mark for assistive tech.

A file: mark memoizes its content and re-reads on an mtime change (the Configuration#openapi_document posture), so editing the SVG in development shows up without a server restart.

Constant Summary collapse

FORM_KEYS =

The config keys that each select a render form — exactly one must be given.

%i[svg paths markup file src].freeze
SVG_SHAPE =

A loose "is this an element" shape check for the markup:/file: forms.

/\A\s*<svg[\s>]/i
DEFAULT_VIEWBOX = 
"0 0 24 24"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attrs = {}) ⇒ BrandLogo

Returns a new instance of BrandLogo.



44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/docs_kit/brand_logo.rb', line 44

def initialize(attrs = {})
  attrs = attrs.transform_keys(&:to_sym)
  given = attrs.slice(*FORM_KEYS).compact
  unless given.size == 1
    raise ArgumentError,
          "brand_logo takes exactly one of #{FORM_KEYS.inspect} (got #{given.keys.inspect})"
  end

  @viewbox = attrs[:viewbox] || DEFAULT_VIEWBOX
  @label = attrs[:label]
  @alt = attrs[:alt]
  build_form(given.keys.first, attrs)
end

Instance Attribute Details

#file ⇒ Object (readonly)

Returns the value of attribute file.



34
35
36
 
# File 'lib/docs_kit/brand_logo.rb', line 34

def file
  @file
end

#markup ⇒ Object (readonly)

Returns the value of attribute markup.



34
35
36
 
# File 'lib/docs_kit/brand_logo.rb', line 34

def markup
  @markup
end

#paths ⇒ Object (readonly)

Returns the value of attribute paths.



34
35
36
 
# File 'lib/docs_kit/brand_logo.rb', line 34

def paths
  @paths
end

#src ⇒ Object (readonly)

Returns the value of attribute src.



34
35
36
 
# File 'lib/docs_kit/brand_logo.rb', line 34

def src
  @src
end

#viewbox ⇒ Object (readonly)

Returns the value of attribute viewbox.



34
35
36
 
# File 'lib/docs_kit/brand_logo.rb', line 34

def viewbox
  @viewbox
end

Class Method Details

.from(logo) ⇒ Object

Coerce a config value (Hash with symbol or string keys, or an already-normalized BrandLogo) into a BrandLogo.



38
39
40
41
42
 
# File 'lib/docs_kit/brand_logo.rb', line 38

def self.from()
  return  if .is_a?(self)

  new(.to_h)
end

Instance Method Details

#alt ⇒ Object 



72
 
# File 'lib/docs_kit/brand_logo.rb', line 72

def alt = @alt || @label

#embed? ⇒ Boolean

Whether the mark embeds site-authored markup verbatim (markup: or file:).

Returns:

  • (Boolean) 


67
 
# File 'lib/docs_kit/brand_logo.rb', line 67

def embed? = markup? || file?

#file? ⇒ Boolean

Returns:

  • (Boolean) 


63
 
# File 'lib/docs_kit/brand_logo.rb', line 63

def file? = !file.nil?

#image? ⇒ Boolean

Returns:

  • (Boolean) 


64
 
# File 'lib/docs_kit/brand_logo.rb', line 64

def image? = !src.nil?

#inline? ⇒ Boolean

Returns:

  • (Boolean) 


61
 
# File 'lib/docs_kit/brand_logo.rb', line 61

def inline? = !paths.nil?

#label ⇒ Object

The accessible name — label falls back to alt (and vice versa) so a site setting either names the mark; nil defers to the render-time brand fallback.



71
 
# File 'lib/docs_kit/brand_logo.rb', line 71

def label = @label || @alt

#markup? ⇒ Boolean

Returns:

  • (Boolean) 


62
 
# File 'lib/docs_kit/brand_logo.rb', line 62

def markup? = !markup.nil?

#svg ⇒ Object

The single path-d, for the landing-compat svg: shape (first of #paths).



59
 
# File 'lib/docs_kit/brand_logo.rb', line 59

def svg = paths&.first

#svg_markup ⇒ Object

The markup to embed: the literal markup: string, or the file's content — memoized per mtime so a dev edit re-reads without a restart.



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/docs_kit/brand_logo.rb', line 76

def svg_markup
  return @markup if markup?

  mtime = begin
    @file.mtime
  rescue StandardError
    nil
  end
  return @file_content if defined?(@file_content) && @file_mtime == mtime

  @file_mtime = mtime
  @file_content = check_svg_shape!(@file.read, "file #{@file}")
end