kirana 0.1.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec04ffb0d1203c354bee5abaa99909fc167c3e3ab58c045371fab59ba32e89dc
+  data.tar.gz: 985f62160305402c359939eaad2e6a0af6bc8f086d59c80d90e76d9592115ae2
+SHA512:
+  metadata.gz: 3ab74b718e0639a6d02eab20f7e8ef54bbf60f6de8534afca861a9074d9890cc679fcd6086a6017fa310f5893ec6328bd45e85dd411d53f6a2db5254cd623b2e
+  data.tar.gz: c2be4913738f14e7e7c093bf34091e499dc1d2624b4d94c9b292198a5eb32a00a375a2cf9aa37defcc580086461d141ae2565aec52cf6db4867ac2c90952d367

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirana authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,14 @@
+# kirana (Ruby)
+
+Kirana for Rails templates (D-069): the `kirana` view helper, which reads the class map
+`kirana build` and `kirana dev` write and merges named styles the way `sx` does.
+
+```erb
+<div class="<%= kirana :card, active && "card.active" %>">…</div>
+```
+
+The Railtie adds the helper to every view; `config.kirana.classes` overrides the default
+`public/kirana/classes.json`. The map is read again whenever it changes. Outside Rails,
+`Kirana::ClassMap.from_file(path).classes(:card)`.
+
+`bundle exec rake test` runs the tests, the merge vectors included, at 100 % of lines and branches.

data/lib/kirana/class_map.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kirana
+  # A class map (D-069): the class string of every handle a server app's style modules export, by
+  # name, as `kirana build` and `kirana dev` write it. `classes` merges named handles the way `sx`
+  # merges them, later ones winning.
+  class ClassMap
+    # A name the class map does not list.
+    class UnknownStyle < KeyError; end
+
+    def initialize(map)
+      raise ArgumentError, "kirana: this class map was written by another version of Kirana; rebuild it" unless map["version"] == 1
+
+      @classes = map.fetch("classes", {})
+      families = map.fetch("families", {})
+      @merge = Merge.new(map.fetch("prefix", "k"), families.fetch("four", 0), families.fetch("two", 0))
+    end
+
+    # Reads the class map `kirana build` or `kirana dev` wrote.
+    def self.from_file(path)
+      raise Errno::ENOENT, "kirana: no class map at #{path}; run `kirana dev` or `kirana build` first" unless File.file?(path)
+
+      new(JSON.parse(File.read(path)))
+    end
+
+    # The classes of the named handles, merged: `classes(:card, active && "card.active")`. Falsy names
+    # are skipped, so a condition can leave one out.
+    def classes(*names)
+      strings = names.reject { |name| !name || name.to_s.empty? }.map do |name|
+        @classes.fetch(name.to_s) { raise UnknownStyle, "kirana: no style named \"#{name}\" in the class map" }
+      end
+      @merge.dom(strings)
+    end
+
+    # Whether the map has a handle by this name.
+    def key?(name)
+      @classes.key?(name.to_s)
+    end
+  end
+
+  class << self
+    # Where the class map is: set by the Railtie from `config.kirana.classes`.
+    attr_writer :classes_path
+
+    def classes_path
+      @classes_path || "public/kirana/classes.json"
+    end
+
+    # The class map at `classes_path`, read again when the file changes (`kirana dev` rewrites it).
+    def class_map
+      stamp = File.file?(classes_path) && File.mtime(classes_path)
+      @class_map = nil unless @stamp == stamp && @path == classes_path
+      @stamp = stamp
+      @path = classes_path
+      @class_map ||= ClassMap.from_file(classes_path)
+    end
+  end
+
+  # The view helper: `<div class="<%= kirana :card, active && "card.active" %>">`.
+  module Helper
+    def kirana(*names)
+      Kirana.class_map.classes(*names)
+    end
+  end
+end

data/lib/kirana/merge.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Kirana
+  # Kirana's class merge, as the private runtime does it (`@kirana/core/internal`, D-018), for
+  # templates that hold class strings from a class map (D-069).
+  #
+  # Kirana class names are `{prefix}{key}_{value}`: merging keeps the last class per key, a
+  # `{prefix}{key}_` tombstone removes one key, `{prefix}{property}*_` removes every key of a
+  # property, and `{prefix}{shorthand}/{codes}{scope}_` unfolds a shorthand atom into longhands.
+  # Classes without the prefix pass through in order. Held to the runtime by
+  # `fixtures/merge/vectors.json`.
+  class Merge
+    # `four`: property codes below it are four-longhand box families; `two`: codes from `four` below
+    # it are two-longhand families.
+    def initialize(prefix, four, two)
+      @prefix = prefix
+      @four = four
+      @two = two
+    end
+
+    # Every class the strings merge to, in merge order, tombstones included.
+    def merge(strings)
+      classes = {}
+      strings.each do |string|
+        string.split(" ").each { |token| classes = add(classes, token) }
+      end
+      classes.values
+    end
+
+    # The classes an element receives: the merge without its tombstones.
+    def dom(strings)
+      merge(strings).reject { |token| token.end_with?("_") }.join(" ")
+    end
+
+    private
+
+    def add(classes, token)
+      finish = token.rindex("_")
+      unless token.start_with?(@prefix) && finish
+        classes[" #{token}"] = token
+        return classes
+      end
+      key = token[@prefix.length...finish]
+      head = key.split("-", 2).first.to_s
+      remove_longhands(classes, key, head) if head.length < 3
+      slash = key.index("/")
+      if slash&.positive?
+        classes = unfold(classes, key, slash)
+      elsif key.end_with?("*")
+        # A target's own `-xyz*` tombstone has the length of a condition key and must survive.
+        base = key[0...-1]
+        classes.delete_if { |existing, _| scoped?(existing, base, true) && !existing.end_with?("*") }
+      end
+      classes.delete(key)
+      classes[key] = token
+      classes
+    end
+
+    # A box family atom (or its tombstone) replaces its longhands, whose codes follow its own (D-045).
+    def remove_longhands(classes, key, head)
+      index = head.each_char.reduce(0) do |sum, digit|
+        unit = digit.ord
+        (sum * 62) + unit - (if unit > 96 then 87 elsif unit > 64 then 29 else 48 end)
+      end
+      size = if index < @four
+        (index % 5).zero? ? 4 : 0
+      else
+        index < @two && ((index - @four) % 3).zero? ? 2 : 0
+      end
+      rest = key[head.length..]
+      size.downto(1) { |offset| classes.delete(code(index + offset) + rest) }
+    end
+
+    # `{shorthand}/{kept codes}{target}{-conditions | *}`: replace earlier shorthand atoms by atoms of
+    # the kept longhands in their place, reusing each atom's value (D-045).
+    def unfold(earlier, key, slash)
+      every = key.end_with?("*")
+      tail = every ? key[(slash + 1)...-1] : key[(slash + 1)..]
+      dash = tail.index("-")
+      codes = dash ? tail[0...dash] : tail
+      scope = dash ? tail[dash..] : ""
+      shorthand = key[0...slash]
+      classes = {}
+      earlier.each do |existing, atom|
+        if !atom.end_with?("_") && scoped?(existing, shorthand + scope, every)
+          rest = existing[shorthand.length..]
+          codes.split(".").each do |kept|
+            kept += rest
+            # A longhand entry after the atom (not copied yet) was written after it and keeps its
+            # value; one before it is the atom's own tombstone or an earlier, broader atom's value.
+            deleted = classes.key?(kept)
+            classes.delete(kept)
+            classes[kept] = @prefix + kept + atom[atom.rindex("_")..] if deleted || !earlier.key?(kept)
+          end
+        else
+          classes[existing] = atom
+        end
+      end
+      classes
+    end
+
+    # `key` is `base`, or — for every condition set — `base` plus `-` and a 4-character hash.
+    def scoped?(key, base, every)
+      key == base || (every && key.start_with?("#{base}-") && key.length == base.length + 5)
+    end
+
+    # A base-62 property code (`0-9a-zA-Z`) for an index, as class names spell them (D-037).
+    def code(index)
+      prefix = index > 61 ? code(index / 62) : ""
+      index %= 62
+      prefix + (if index < 10 then index + 48 elsif index < 36 then index + 87 else index + 29 end).chr
+    end
+  end
+end

data/lib/kirana/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Kirana
+  # Rails: the `kirana` view helper in every view, and `config.kirana.classes` for where the class
+  # map is (default `public/kirana/classes.json`).
+  class Railtie < ::Rails::Railtie
+    config.kirana = ActiveSupport::OrderedOptions.new
+
+    initializer "kirana.helper" do |app|
+      Kirana.classes_path = (app.config.kirana.classes || app.root.join("public/kirana/classes.json")).to_s
+      ActiveSupport.on_load(:action_view) { include Kirana::Helper }
+    end
+  end
+end

data/lib/kirana.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "kirana/merge"
+require_relative "kirana/class_map"
+
+module Kirana
+  # Loads the Railtie when Rails is present; without it the gem is the class map alone.
+  def self.integrate(rails = defined?(::Rails::Railtie))
+    require_relative "kirana/railtie" if rails
+  end
+end
+
+Kirana.integrate

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: kirana
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre1
+platform: ruby
+authors:
+- The Kirana authors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kirana.rb
+- lib/kirana/class_map.rb
+- lib/kirana/merge.rb
+- lib/kirana/railtie.rb
+homepage: https://kirana.style
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/kirana-style/kirana/tree/main/packages/kirana/helpers/ruby
+  bug_tracker_uri: https://github.com/kirana-style/kirana/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Kirana for Rails templates: the class map reader and the kirana view helper.'
+test_files: []