cleo_design_tokens 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bf05dee064782565d442d3da54c6203328456debe4b7d183ec0e24d582b4a55
-  data.tar.gz: 58af1f5a62cb959dcbadafb2ebece37fa53558b5cd9d6cba683d5a40efa51b16
+  metadata.gz: 4b26b7b458c43724454d2827bf71e276857f7948f46dfade6a22c0a78ed068f3
+  data.tar.gz: 13ff4a6a39778fe89c931a6cd1f01931e3d08b901262aa582bde3b054b366889
 SHA512:
-  metadata.gz: 6a72721e29aad60328fc4b8a61a90ed9107355f2a55d34ffa6adf27e58c6c89449b67ad50f626c0ab56f5ac1290a9bcfa9178643350d6533f7cad3000c4ab179
-  data.tar.gz: 15248d41bac918b3b03e4724182903de1d2d3f2ef4af133412335b563d6477d1ef6b6cd65eb84549a3ec1131d4ca2d407c886693dcc6a50314e2dba5777bcff6
+  metadata.gz: fa1dc9fec6338e93595ef7b0252bd96a7a427b810ef5a262669e89874ded5882377a2a2fa6318e13d335b721af4e45f1e3e959fb72355d9165101307998a96ad
+  data.tar.gz: ff7a54aa890e5ebf7a3dce4d1364db1ce7e9ac6312f04fa7ac949d4f49582fce02218ddbebef0a1e0e77c093f88c82a235dc93f1a80480589a4f307681ee067b

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,57 @@
+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)
+      Palette.new(
+        primitives: LookupBuilder.build_lookup(@primitives, experience: experience).freeze,
+        semantic: LookupBuilder.build_semantic_lookup(@semantic, experience: experience).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,20 @@ 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)
+      flatten_tree(tree) { |leaf, key| semantic_entry(experience_leaf(leaf, experience, key), experience, key) }
     end
 
     # Walks `tree`, turning each leaf into a lookup entry via the block —
@@ -43,19 +49,48 @@ 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)
       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) ? override["$value"] : 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 = leaf["$value"]
+      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
   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.2",
+  "version": "0.2.4",
   "description": "Canonical source of truth for Cleo's design tokens (DTCG JSON), plus a TypeScript reader.",
   "type": "module",
   "license": "UNLICENSED",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cleo_design_tokens
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Cleo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies: []
 description: Flattens Cleo's colour design tokens (packages/tokens/tokens/color) into
   frozen colors.primitives / colors.semantic lookups, with the theme passed alongside
@@ -20,6 +20,7 @@ extra_rdoc_files: []
 files:
 - lib/cleo_design_tokens.rb
 - lib/cleo_design_tokens/bucket.rb
+- lib/cleo_design_tokens/configuration.rb
 - lib/cleo_design_tokens/errors.rb
 - lib/cleo_design_tokens/lookup_builder.rb
 - lib/cleo_design_tokens/semantic_bucket.rb