cleo_design_tokens 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8ed2bf7065eaea99e6dd21e5af3658571a15e58875f66cf890fc544260d1dc0
-  data.tar.gz: 4d27e344661369e8d8ba2ab21b4e9d6c07363bf1d8da909e366aeef54bffcd49
+  metadata.gz: 0a44c38f546ec1f31af8273066fa31c77538d6e9812225b0da0a763e5622afa6
+  data.tar.gz: 4a141717fc6df4973d260296903ce7e0f95525c6f9caee385ddf166877e7b615
 SHA512:
-  metadata.gz: f211a9378781015279f633200656d71f3a7606c90ea13d2cb48d82d9e4ace0b54443842c30674c0cc1195b43c918fc74d0830323c6fe68ac3ff18c9f363b644a
-  data.tar.gz: '078f30070c8c51f98ac88cfbdce950bec4f77abf66a4bdc6933127f9f666787faadd3f7be4aae624cc1b46022ae6a64b732428f3b3363058c17b61b5bab8761d'
+  metadata.gz: 9049839cd022f9c7cb925a3c443ccad2e0ae2145d68d463bfc19afc2cc55564e52b496f09c6c9cb93a3835a73d25cc975e3b6c8c078cdaa3afc02901abec67dc
+  data.tar.gz: 273d641074a554f32656ff6beabf7e723a19f7dff52506f1a57f7119b4821a3fcf6bbeb76a4d3bf7ec0c10d9edfcdd1bfd520284f1bc6bdcb2e882fde9187f87

data/lib/cleo_design_tokens/bucket.rb

@@ -10,7 +10,8 @@ module CleoDesignTokens
     end
 
     def fetch(key)
-      value = @lookup.fetch(key) { raise UnknownTokenError, "unknown design token: #{key.inspect}" }
+      lookup = @lookup.respond_to?(:call) ? @lookup.call : @lookup
+      value = lookup.fetch(key) { raise UnknownTokenError, "unknown design token: #{key.inspect}" }
       # `Hash#fetch` only guards a missing *key* — a key present with a nil
       # value (malformed data: a primitive leaf with no `$value`) would
       # otherwise return nil instead of raising.

data/lib/cleo_design_tokens/configuration.rb

@@ -0,0 +1,58 @@
+require "thread"
+require_relative "lookup_builder"
+
+module CleoDesignTokens
+  class Configuration
+    Palette = Data.define(:primitives, :semantic)
+    CONTEXT_KEY = :cleo_design_tokens_palette
+    private_constant :Palette, :CONTEXT_KEY
+
+    attr_reader :default_palette
+
+    def initialize(primitives:, semantic:)
+      @primitives = primitives
+      @semantic = semantic
+      @default_palette = build_palette(:current)
+      @refresh_palette = nil
+      @mutex = Mutex.new
+    end
+
+    def palette
+      # Thread#[] is fiber-local, unlike Thread#thread_variable_get.
+      Thread.current[CONTEXT_KEY] || default_palette
+    end
+
+    def configure(experience:)
+      selected = case experience
+      when :current, "current" then nil
+      when :refresh, "refresh"
+        @mutex.synchronize { @refresh_palette ||= build_palette(:refresh) }
+      else
+        raise UnknownExperienceError, "unknown experience: #{experience.inspect}; expected :current or :refresh"
+      end
+
+      unless block_given?
+        Thread.current[CONTEXT_KEY] = selected
+        return nil
+      end
+
+      previous = Thread.current[CONTEXT_KEY]
+      begin
+        Thread.current[CONTEXT_KEY] = selected
+        yield
+      ensure
+        Thread.current[CONTEXT_KEY] = previous
+      end
+    end
+
+    private
+
+    def build_palette(experience)
+      primitives = LookupBuilder.build_lookup(@primitives, experience: experience).freeze
+      Palette.new(
+        primitives: primitives,
+        semantic: LookupBuilder.build_semantic_lookup(@semantic, experience: experience, primitives: primitives).freeze,
+      )
+    end
+  end
+end

data/lib/cleo_design_tokens/errors.rb

@@ -1,5 +1,6 @@
 module CleoDesignTokens
   class UnknownTokenError < KeyError; end
   class UnknownThemeError < ArgumentError; end
+  class UnknownExperienceError < ArgumentError; end
   class DuplicateTokenError < KeyError; end
 end

data/lib/cleo_design_tokens/lookup_builder.rb

@@ -9,14 +9,33 @@ module CleoDesignTokens
   module LookupBuilder
     # Flattens one tree of plain (theme-free) leaves — e.g. the parsed
     # `primitives.json` — into a key -> hex lookup.
-    def self.build_lookup(tree)
-      flatten_tree(tree) { |leaf| leaf["$value"].freeze }
+    def self.build_lookup(tree, experience: :current)
+      flatten_tree(tree) do |leaf, key|
+        value = experience_leaf(leaf, experience, key)["$value"]
+        unless value.is_a?(String)
+          raise UnknownExperienceError, "design token #{key.inspect} has no primitive value for experience #{experience.inspect}"
+        end
+        value.freeze
+      end
     end
 
     # Flattens `semantic.json` into a key -> SemanticEntry lookup, one entry
     # per role — the theme axis lives inside the entry, not in the key.
-    def self.build_semantic_lookup(tree)
-      flatten_tree(tree) { |leaf| semantic_entry(leaf) }
+    def self.build_semantic_lookup(tree, experience: :current, primitives: nil)
+      schema = tree["$schema"]
+      if tree.key?("$schema") && schema != "cleo-semantic-references/1"
+        raise UnknownExperienceError, "unsupported semantic schema: #{schema.inspect}"
+      end
+      references = schema == "cleo-semantic-references/1"
+      flatten_tree(tree) do |leaf, key|
+        snapshots = leaf["$experiences"]
+        if references && leaf.key?("$experiences") && !snapshots.is_a?(Hash)
+          raise UnknownExperienceError, "invalid semantic experiences for #{key.inspect}"
+        end
+        shared = references && (experience.to_s == "current" || !snapshots.is_a?(Hash) || !snapshots.key?("cleoRefresh"))
+        snapshot = shared ? leaf : experience_leaf(leaf, experience, key)
+        semantic_entry(snapshot, experience, key, primitives: primitives, references: references)
+      end
     end
 
     # Walks `tree`, turning each leaf into a lookup entry via the block —
@@ -43,20 +62,59 @@ module CleoDesignTokens
         end
 
         origins[key] = path
-        lookup[key] = yield(leaf)
+        lookup[key] = yield(leaf, key)
       end
       lookup
     end
     private_class_method :flatten_tree
 
-    def self.semantic_entry(leaf)
+    def self.experience_leaf(leaf, experience, key)
+      return leaf if experience.to_s == "current"
+      unless experience.to_s == "refresh"
+        raise UnknownExperienceError, "unknown experience: #{experience.inspect}; expected :current or :refresh"
+      end
+
+      snapshots = leaf["$experiences"]
+      snapshot = snapshots["cleoRefresh"] if snapshots.is_a?(Hash)
+      unless snapshot.is_a?(Hash)
+        raise UnknownExperienceError, "experience :refresh is unavailable for design token #{key.inspect}; sync the Refresh colour data first"
+      end
+      snapshot
+    end
+    private_class_method :experience_leaf
+
+    def self.semantic_entry(leaf, experience, key, primitives:, references:)
       themes = {}
-      (leaf["$themes"] || {}).each { |theme, override| themes[theme] = override["$value"].freeze }
+      raw_themes = leaf["$themes"] || {}
+      unless raw_themes.is_a?(Hash)
+        raise UnknownExperienceError, "design token #{key.inspect} has invalid themes for experience #{experience.inspect}"
+      end
+      raw_themes.each do |theme, override|
+        value = override.is_a?(Hash) ? semantic_value(override, key, primitives: primitives, references: references) : nil
+        unless value.is_a?(String)
+          raise UnknownExperienceError, "design token #{key.inspect} has no value for theme #{theme.inspect} in experience #{experience.inspect}"
+        end
+        themes[theme] = value.freeze
+      end
+      value = semantic_value(leaf, key, primitives: primitives, references: references)
+      if (leaf.key?("$value") && !value.is_a?(String)) || (value.nil? && themes.empty?)
+        raise UnknownExperienceError, "design token #{key.inspect} has no semantic values for experience #{experience.inspect}"
+      end
 
       # `Data#new` freezes the instance itself; the Hash inside it still
       # needs its own `.freeze` — freezing is shallow.
-      SemanticEntry.new(leaf["$value"]&.freeze, themes.freeze)
+      SemanticEntry.new(value&.freeze, themes.freeze)
     end
     private_class_method :semantic_entry
+
+    def self.semantic_value(binding, key, primitives:, references:)
+      return binding["$value"] unless references && binding.key?("$ref")
+      ref = binding["$ref"]
+      if !ref.is_a?(String) || !primitives&.key?(ref) || binding.key?("$value")
+        raise UnknownExperienceError, "invalid primitive reference #{ref.inspect} for #{key.inspect}"
+      end
+      primitives.fetch(ref)
+    end
+    private_class_method :semantic_value
   end
 end

data/lib/cleo_design_tokens/semantic_bucket.rb

@@ -16,7 +16,8 @@ module CleoDesignTokens
       theme = theme.to_s
       raise UnknownThemeError, "unknown theme: #{theme.inspect}" unless THEMES.include?(theme)
 
-      entry = @lookup.fetch(key) { raise UnknownTokenError, "unknown design token: #{key.inspect}" }
+      lookup = @lookup.respond_to?(:call) ? @lookup.call : @lookup
+      entry = lookup.fetch(key) { raise UnknownTokenError, "unknown design token: #{key.inspect}" }
       value = resolve(entry, theme)
       if value.nil?
         raise UnknownTokenError,

data/lib/cleo_design_tokens.rb

@@ -8,6 +8,7 @@ require_relative "cleo_design_tokens/version"
 require_relative "cleo_design_tokens/lookup_builder"
 require_relative "cleo_design_tokens/bucket"
 require_relative "cleo_design_tokens/semantic_bucket"
+require_relative "cleo_design_tokens/configuration"
 
 # Reads Cleo's canonical colour design tokens (packages/tokens/tokens/color)
 # into two frozen lookups, namespaced by token type then layer, with the
@@ -27,8 +28,13 @@ module CleoDesignTokens
   # Built at load, into constants — not `@lookup ||=`, which would race under
   # concurrent access. Frozen from the moment the gem loads, so every reader
   # in every thread sees the same immutable lookup.
-  PRIMITIVES_LOOKUP = LookupBuilder.build_lookup(JSON.parse(File.read(PRIMITIVES_PATH))).freeze
-  SEMANTIC_LOOKUP = LookupBuilder.build_semantic_lookup(JSON.parse(File.read(SEMANTIC_PATH))).freeze
+  CONFIGURATION = Configuration.new(
+    primitives: JSON.parse(File.read(PRIMITIVES_PATH)),
+    semantic: JSON.parse(File.read(SEMANTIC_PATH)),
+  )
+  private_constant :CONFIGURATION
+  PRIMITIVES_LOOKUP = CONFIGURATION.default_palette.primitives
+  SEMANTIC_LOOKUP = CONFIGURATION.default_palette.semantic
 
   # Namespaced by token type (`colors`), then by layer (`primitives`,
   # `semantic`) — lowercase accessors, not `CleoDesignTokens::Colors::
@@ -40,12 +46,19 @@ module CleoDesignTokens
   # no `.primitives` method. Plural `Colors`, not `Color` — an instance
   # holds both buckets for the `colors` token type, not a single colour.
   Colors = Data.define(:primitives, :semantic)
-  COLORS = Colors.new(primitives: Bucket.new(PRIMITIVES_LOOKUP), semantic: SemanticBucket.new(SEMANTIC_LOOKUP))
+  COLORS = Colors.new(
+    primitives: Bucket.new(-> { CONFIGURATION.palette.primitives }),
+    semantic: SemanticBucket.new(-> { CONFIGURATION.palette.semantic }),
+  )
 
   def self.colors
     COLORS
   end
 
+  def self.configure(experience:, &block)
+    CONFIGURATION.configure(experience: experience, &block)
+  end
+
   # Spacing is code-owned, not generated from Figma. Without a unit it is a
   # numeric React Native-ready pixel value; CSS callers opt into a unit.
   def self.spacing(multiplier, unit: nil)

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meetcleo/design-tokens",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Canonical source of truth for Cleo's design tokens (DTCG JSON), plus a TypeScript reader.",
   "type": "module",
   "license": "UNLICENSED",