daisyui 2.1.0 → 2.2.0

data/exe/daisyui-tailwind

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "daisyui"
+
+exit DaisyUI::Tailwind::Command.run(ARGV)

data/lib/daisy_ui/base.rb

@@ -35,6 +35,8 @@ module DaisyUI
   # This renders: <div class="[generated classes]" id="..." data-...="..." ...>
   #
   class Base < Phlex::HTML
+    include Variants::Rendering
+
     BOOLS = [true, false].freeze
     # Shared color modifiers used across multiple components
     # Maps color names to their DaisyUI background/text class combinations
@@ -145,6 +147,16 @@ module DaisyUI
         @component_class = Shareable.share(component_class)
       end
 
+      # What a `variants` block declared beyond modifiers: base, defaults,
+      # compounds, states, `on` rules and slots (see DaisyUI::Variants).
+      def variant_definitions
+        @variant_definitions || Variants::EMPTY
+      end
+
+      def variant_definitions=(definitions)
+        @variant_definitions = Shareable.share(definitions)
+      end
+
       # Positional symbols a component handles itself (e.g. Dropdown's
       # :popover): accepted as modifiers, but they emit no class.
       def flags
@@ -183,6 +195,7 @@ module DaisyUI
         subclass.modifiers = (modifiers || {}).dup
         subclass.modifier_groups = modifier_groups.transform_values(&:dup)
         subclass.flags = flags.dup
+        subclass.variant_definitions = variant_definitions
         # Inherit component_class if it was explicitly set
         return unless instance_variable_defined?(:@component_class)
 
@@ -216,11 +229,15 @@ module DaisyUI
         ClassMerge.reset!
       end
 
+      # Declares variants, compounds, defaults, states and slots; returns the
+      # declarations, so `Widget.variants.schema` describes them.
+      def variants(&) = Variants.build(self, &)
+
       # @api private Called by DaisyUI.finalize! for every component: derives
       # component_class on the main Ractor and makes sure every registry is
       # frozen for non-main Ractors.
       def finalize!
-        [component_class, modifiers, modifier_groups, flags].each { |registry| Shareable.share(registry) }
+        [component_class, modifiers, modifier_groups, flags, variant_definitions].each { |registry| Shareable.share(registry) }
         self
       end
     end
@@ -246,17 +263,20 @@ module DaisyUI
     # Main extension points - override these in your project!
 
     # Builds the final CSS class string from:
-    # 1. Component base class (e.g., "dropdown")
+    # 1. Component base class (e.g., "dropdown"), then a `variants` base
     # 2. Modifier classes (e.g., "dropdown-top")
-    # 3. Responsive classes (e.g., "sm:dropdown-hover")
-    # 4. User-provided classes via `class:` option
+    # 3. What a `variants` block derives: defaults, compounds, `on` states
+    # 4. Responsive classes (e.g., "sm:dropdown-hover")
+    # 5. User-provided classes via `class:` option
     #
     # Note: This method DESTRUCTIVELY removes :class from options
     # so it won't appear again in attributes
     def classes
       merge_classes(
         base_class,
+        variant_base_classes,
         *modifier_classes,
+        *variant_classes,
         *responsive_classes,
         options.delete(:class)
       )

data/lib/daisy_ui/engine.rb

@@ -11,6 +11,10 @@ module DaisyUI
   #   * appends the JS dir to the asset load path so Propshaft/Sprockets serve
   #     the .min.js and its sourcemap (Sprockets also needs them precompiled).
   #
+  # Rails also loads lib/tasks/daisyui.rake from here: `bin/rails
+  # daisyui:tailwind[OUTPUT]` writes the Tailwind sources of the app's own
+  # components (DaisyUI::Tailwind::AppSources).
+  #
   # The controllers are opt-in at the markup level (`Dropdown(:popover, stimulus:
   # true)`, `Tooltip(:popover)`) and not preloaded, so a page that never uses
   # one never fetches it.

data/lib/daisy_ui/mcp_server/variants_guide.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  class McpServer
+    # The text of the `variants_guide` tool: the `variants` DSL on one page, with
+    # the three ways it surprises. Keep it in step with the README's "Variants,
+    # states and slots" and the docs site page.
+    module VariantsGuide
+      TEXT = <<~MARKDOWN
+        # Variants, states and slots
+
+        A component that owns its design declares it in a `variants` block on a
+        `DaisyUI::Base` subclass. `get_component` shows the result as a schema.
+
+        ```ruby
+        class Widget < DaisyUI::Button
+          variants do
+            base "font-medium"
+            variant :size, sm: "btn-sm", md: "btn-md"
+            default :size, :md
+            compound style: :outline, color: nil, class: "[--btn-bg:var(--color-base-100)]"
+            state :hover, "hover"
+            on :hover, style: %i[ghost link], class: "[--btn-bg:transparent]"
+          end
+        end
+        ```
+
+        ## Which declaration
+
+        | Need | Use |
+        |---|---|
+        | Alternatives, only one applies (sizes, colors) | `variant :group, member: "classes"` |
+        | An on/off modifier | `flag :name, "classes"`; `flag :name` alone has no class and exists to be matched |
+        | Classes every instance gets | `base "classes"` (appended to the inherited base) |
+        | A member when the caller names none of the group | `default :group, :member` |
+        | Classes when modifiers hold together or one is absent | `compound(**match, class:, set: {})` |
+        | The same classes under a browser state | `state :name, "<tailwind variant>"` once, then `on(states, **match, class:)` |
+        | A part of the component (trigger, menu) | `slot :name, "classes"`, then `slot_classes(name, options)` / `slot_options(name, options)` in the part's method |
+
+        ## Match values (`compound`, `on`)
+
+        | Value | Holds when |
+        |---|---|
+        | `:member` | that member is selected: given, defaulted or set by an earlier compound |
+        | `[:a, :b]` | any of them is; a `nil` in the list means "or none": `shape: [nil, :row]` |
+        | `nil` / `false` | no member of the group is |
+        | `true` | any member of the group is: `color: true` |
+        | `true` / `false` | for a flag: on / off |
+
+        `set: { group: :member }` on a compound selects a member for the caller's empty
+        groups; later compounds see it. `class` and `set` are reserved keys: a group called that could never be matched.
+        A `class:` or a modifier value can be a Hash keyed by slot (`root` is the component).
+
+        ## Render order
+
+        component class, `base`, the caller's modifiers, defaulted and set members,
+        compounds, `on` rules, `responsive:`, then the caller's `class:`. ClassMerge
+        resolves conflicts, the last one wins.
+
+        ## Pitfalls
+
+        1. A `default` renders after the caller's modifiers. A default member's class
+           beats a caller modifier that sets the same property (a default size's
+           `--fontsize` beats an `:inline` modifier's). Put a value both can set in
+           `base`, not in a default.
+        2. A compound or `on` rule also renders after the caller's modifiers, so it
+           can override a modifier's arbitrary property. Leave the conflicting member
+           out of the match (`layout: [nil, :inline, :row]`).
+        3. `on` writes `"<state>:<class>"`: the state prefix is outermost. A rule that
+           needs a child selector first (`[&_li]:hover:bg-...`) cannot be an `on :hover`
+           rule; keep it literal in `base`.
+
+        Also: do not name a group after an inherited one with a different meaning
+        (`Button` already has `shape`); a state selector with a child combinator puts `>`
+        in the class attribute, so parse rendered HTML with Nokogiri, not a regexp.
+
+        ## Tailwind sources
+
+        Tailwind v4 compiles only classes written out literally, and an `on` class is
+        written nowhere. Generate sources for your own components, commit the file,
+        import it from the Tailwind entry and fail a spec when it is stale:
+
+        ```sh
+        bin/rails "daisyui:tailwind[app/assets/stylesheets/generated/daisyui_app.css]"
+        bundle exec daisyui-tailwind --app --require ./config/components.rb -o app/assets/stylesheets/generated/daisyui_app.css
+        ```
+
+        ```ruby
+        expect(DaisyUI::Tailwind.stale?("app/assets/stylesheets/generated/daisyui_app.css")).to be(false)
+        ```
+
+        ## Introspection
+
+        `Widget.variants.schema` returns `base`, `variants`, `flags`, `defaults`,
+        `compounds`, `on`, `states` and `slots` as frozen data.
+      MARKDOWN
+    end
+  end
+end

data/lib/daisy_ui/mcp_server.rb

@@ -18,7 +18,7 @@ module DaisyUI
       },
       {
         name: "get_component",
-        description: "Get detailed information about a specific DaisyUI component including all modifiers and usage examples",
+        description: "Get detailed information about a specific DaisyUI component including all modifiers, its variants schema (groups, flags, defaults, compounds, on rules, states, slots) and usage examples",
         inputSchema: {
           type: "object",
           properties: {
@@ -37,6 +37,11 @@ module DaisyUI
           },
           required: ["query"]
         }
+      },
+      {
+        name: "variants_guide",
+        description: "How to declare a component's design with the variants DSL (variant, flag, default, compound, state/on, slot): when to use which, the match values, render order and the pitfalls",
+        inputSchema: { type: "object", properties: {}, required: [] }
       }
     ].freeze
     Shareable.make(TOOLS) # the Hashes inside too
@@ -113,6 +118,8 @@ module DaisyUI
         get_component(arguments["component"])
       when "search_components"
         search_components(arguments["query"])
+      when "variants_guide"
+        VariantsGuide::TEXT
       else
         return { content: [{ type: "text", text: "Unknown tool: #{tool_name}" }], isError: true }
       end
@@ -160,6 +167,14 @@ module DaisyUI
         ## Available Modifiers
         #{modifier_list.empty? ? 'No modifiers' : modifier_list}
 
+        ## Variants schema
+
+        Groups, flags, defaults, compounds, `on` rules, states and slots. `variants_guide` explains them.
+
+        ```json
+        #{JSON.pretty_generate(klass.variants.schema)}
+        ```
+
         ## Usage Examples
 
         ```ruby

data/lib/daisy_ui/tailwind/app_sources.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  module Tailwind
+    # The Tailwind sources for an app's own components (DaisyUI::Base
+    # subclasses outside the gem), read from their declarations rather than
+    # the gem's manifest: the component class, every modifier, and what a
+    # `variants` block declares, `on` rules written out once per state. Those
+    # state-prefixed classes appear nowhere literally in the app's source, so
+    # Tailwind only compiles them from here.
+    #
+    # One `@source inline(…)` per component, sorted by name, under a header
+    # with no version, so the file changes only when a declaration does: it
+    # is meant to be committed, and DaisyUI::Tailwind.stale? checks it.
+    class AppSources
+      HEADER = "/* Generated by daisyui-tailwind --app from the app's DaisyUI components: do not edit. */\n"
+
+      def initialize(components, responsive: [], prefix: nil)
+        anonymous = components.reject(&:name)
+        raise ArgumentError, "an anonymous class has no name to label its block: #{anonymous.inspect}" unless anonymous.empty?
+
+        @components = components.sort_by(&:name)
+        @breakpoints = responsive.map(&:to_s)
+        @prefix = prefix.to_s
+        Sources.validate_options!(@breakpoints, @prefix)
+      end
+
+      def render(format)
+        case format.to_s
+        when "css" then to_css
+        when "json" then to_json
+        else raise ArgumentError, "unknown format #{format.inspect}: css or json"
+        end
+      end
+
+      def to_css
+        return "#{HEADER}/* No app components. */\n" if @components.empty?
+
+        lines = @components.flat_map { |component| ["/* #{component.name} */", %(@source inline("#{classes(component).join(' ')}");)] }
+        "#{HEADER}#{lines.join("\n")}\n"
+      end
+
+      def to_json(*)
+        require "json"
+
+        components = @components.to_h do |component|
+          [component.name, { "name" => component.component_class&.to_s, "classes" => classes(component) }]
+        end
+        json = { "components" => components, "classes" => components.values.flat_map { |entry| entry["classes"] }.uniq.sort }
+        "#{JSON.pretty_generate(json)}\n"
+      end
+
+      private
+
+      def classes(component)
+        classes = component.variants.literal_classes(prefix: @prefix) + responsive_classes(component)
+        invalid = classes.reject { |token| Candidate.valid?(token) }
+        return classes.uniq.sort if invalid.empty?
+
+        raise ArgumentError, "#{component.name} declares #{invalid.map(&:inspect).join(', ')}, " \
+                             "which Tailwind cannot read from @source inline(…)"
+      end
+
+      # What `responsive:` renders: the component class and the modifiers.
+      def responsive_classes(component)
+        return [] if @breakpoints.empty?
+
+        tokens = [component.component_class&.to_s, *(component.modifiers || {}).values].compact.flat_map(&:split)
+        @breakpoints.flat_map { |breakpoint| tokens.map { |token| "#{breakpoint}:#{@prefix}#{token}" } }
+      end
+    end
+  end
+end

data/lib/daisy_ui/tailwind/candidate.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  module Tailwind
+    # Which words can go into Tailwind's `@source inline("…")`. inline() is a
+    # quoted string with brace expansion, and one unbalanced bracket in it
+    # makes Tailwind drop every class after it, so a candidate starts and ends
+    # like a utility or variant, has balanced () and [], and holds no quote,
+    # brace, semicolon, backslash or backtick. A `/` only introduces a
+    # fraction or an opacity (`w-1/2`, `bg-base-100/50`), never a path.
+    #
+    # @api private
+    module Candidate
+      SHAPE = /\A[a-z@!\[*-][^\s"'`;{}\\]*[a-z0-9\])%!]\z/
+      PATH = %r{/(?![0-9\[])}
+      CLOSING = { ")" => "(", "]" => "[" }.freeze
+
+      class << self
+        def valid?(token)
+          SHAPE.match?(token) && token.match?(/[a-z]/) && !PATH.match?(token) && balanced?(token)
+        end
+
+        # The candidates among the whitespace-separated words of `classes`.
+        def tokens(classes)
+          classes.split.select { |token| valid?(token) }
+        end
+
+        private
+
+        def balanced?(token)
+          open = []
+          token.each_char do |char|
+            if CLOSING.value?(char)
+              open << char
+            elsif CLOSING.key?(char)
+              return false unless open.pop == CLOSING[char]
+            end
+          end
+          open.empty?
+        end
+      end
+    end
+  end
+end

data/lib/daisy_ui/tailwind/command.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  module Tailwind
+    # `daisyui-tailwind`: the Tailwind sources for the components an app uses,
+    # for its CSS build to call (`bundle exec daisyui-tailwind app -o …`).
+    # Returns the exit status; usage errors print to `err` and return 1.
+    class Command
+      BANNER = <<~TEXT
+        Usage: daisyui-tailwind [options] [PATH...]
+
+        Prints Tailwind CSS v4 sources (@source inline) for the DaisyUI components
+        that the Ruby and templates under each PATH use, plus the components those
+        render. @import the output from your Tailwind entry.
+
+        With --app, prints the sources of the app's own components (DaisyUI::Base
+        subclasses, after requiring each --require FILE) instead: their variants,
+        compounds and state-prefixed classes, for a file you commit.
+
+      TEXT
+
+      def self.run(argv, out: $stdout, err: $stderr) = new(out:, err:).run(argv)
+
+      def initialize(out:, err:)
+        @out = out
+        @err = err
+      end
+
+      def run(argv)
+        require "optparse"
+
+        options = { components: [], format: "css", responsive: [], require: [] }
+        parser = parser(options)
+        paths = parser.parse(argv)
+        return help(parser) if options[:help]
+        return usage(parser) if paths.empty? && options[:components].empty? && !options[:app]
+
+        result = Tailwind.sources(scan: paths, **sources_options(options))
+        options[:output] ? write(options[:output], result) : @out.write(result)
+        0
+      rescue OptionParser::ParseError, ArgumentError, SystemCallError, LoadError => e
+        @err.puts "daisyui-tailwind: #{e.message}"
+        1
+      end
+
+      private
+
+      def parser(options)
+        OptionParser.new do |opts|
+          opts.banner = BANNER
+          opts.on("-c", "--component NAMES", Array, "Components to include, e.g. Button,Navbar (repeatable)") do |names|
+            options[:components].concat(names)
+          end
+          opts.on("-f", "--format FORMAT", %w[css json], "css (default) or json") { |format| options[:format] = format }
+          opts.on("-o", "--output FILE", "Write to FILE, only when its content changes") { |file| options[:output] = file }
+          opts.on("--responsive BREAKPOINTS", Array, "Add breakpoint variants, e.g. sm,md,lg") do |breakpoints|
+            options[:responsive].concat(breakpoints)
+          end
+          opts.on("--prefix PREFIX", "The DaisyUI.configuration.prefix your app sets") { |prefix| options[:prefix] = prefix }
+          opts.on("--app", "The app's own components instead of the gem's") { options[:app] = true }
+          opts.on("-r", "--require FILE", "With --app: load FILE first, e.g. config/environment.rb (repeatable)") do |file|
+            options[:require] << file
+          end
+          opts.on("-h", "--help", "Show this help") { options[:help] = true }
+        end
+      end
+
+      # With --app: load the app's files, then freeze DaisyUI as boot does.
+      def sources_options(options)
+        if options[:app]
+          options[:require].each { |file| require File.expand_path(file) }
+          DaisyUI.finalize!
+        end
+        options.slice(:components, :format, :responsive, :prefix, :app)
+      end
+
+      def help(parser)
+        @out.puts parser
+        0
+      end
+
+      def usage(parser)
+        @err.puts parser
+        1
+      end
+
+      # Only on change: a CSS watcher that sees its own input rewritten on
+      # every build rebuilds forever.
+      def write(path, content)
+        if File.exist?(path) && File.read(path) == content
+          @err.puts "daisyui-tailwind: #{path} is up to date"
+        else
+          require "fileutils"
+
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, content)
+          @err.puts "daisyui-tailwind: wrote #{path}"
+        end
+      end
+    end
+  end
+end

data/lib/daisy_ui/tailwind/lexer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  module Tailwind
+    # Reads a component's Ruby the way the manifest needs it: the words of its
+    # string literals (where its sub-part classes live, e.g. "card-body") and
+    # the constants its code references (the components it renders). Ripper
+    # keeps comments out of both.
+    #
+    # @api private
+    module Lexer
+      class << self
+        def strings(source)
+          tokens(source, :on_tstring_content).flat_map(&:split)
+        end
+
+        def constants(source)
+          tokens(source, :on_const).uniq
+        end
+
+        private
+
+        def tokens(source, type)
+          require "ripper"
+
+          ::Ripper.lex(source).filter_map { |(_position, kind, token)| token if kind == type }
+        end
+      end
+    end
+  end
+end

data/lib/daisy_ui/tailwind/manifest.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  module Tailwind
+    # The committed tailwind_manifest.json: per component (by short name, "Button"),
+    # its class, daisyUI name, files, the components it renders and its
+    # classes; `shared` is base.rb, which every component draws on. The JSON
+    # is the contract for build scripts in other languages, so its keys are
+    # documented in the README.
+    class Manifest
+      def self.load(path = MANIFEST_PATH, root: ROOT)
+        require "json"
+
+        new(JSON.parse(File.read(path)), root:)
+      end
+
+      attr_reader :components, :shared, :root
+
+      def initialize(data, root: ROOT)
+        @components = data.fetch("components")
+        @shared = data.fetch("shared")
+        @root = root
+      end
+
+      def component_names = components.keys
+
+      # `names` ("Button" or "DaisyUI::Button") plus every component they
+      # render, transitively. Sorted.
+      def resolve(names)
+        resolved = []
+        pending = names.map { |name| canonical(name) }
+        until pending.empty?
+          name = pending.pop
+          next if resolved.include?(name)
+
+          resolved << name
+          pending.concat(components.fetch(name)["depends_on"])
+        end
+        resolved.sort
+      end
+
+      # Absolute paths of the components' files, for a literal `@source`.
+      def files(names) = names.flat_map { |name| absolute(components.fetch(name)["files"]) }
+
+      def shared_files = absolute(shared["files"])
+
+      private
+
+      def canonical(name)
+        short = name.to_s.delete_prefix("DaisyUI::")
+        return short if components.key?(short)
+
+        raise UnknownComponentError.new(name, component_names)
+      end
+
+      def absolute(paths) = paths.map { |path| File.join(root, path) }
+    end
+  end
+end

data/lib/daisy_ui/tailwind/manifest_builder.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module DaisyUI
+  module Tailwind
+    # Builds data/daisyui/tailwind_manifest.json from the components
+    # themselves (`bundle exec rake tailwind:manifest`); the manifest spec
+    # fails while the committed file differs. Per component:
+    #
+    # - `classes`: its component class (a Symbol Tailwind cannot see), its
+    #   registered modifiers and the class words in its Ruby's strings
+    # - `modifiers`: the registered modifier classes, which `responsive:`
+    #   can prefix with a breakpoint
+    # - `depends_on`: the other components its code references
+    #
+    # @api private
+    module ManifestBuilder
+      SCHEMA = 1
+      SHARED_FILE = "lib/daisy_ui/base.rb"
+
+      class << self
+        def build(root: ROOT)
+          components = gem_components(File.join(root, "lib", "daisy_ui"))
+          names = components.map(&:first)
+          {
+            "schema" => SCHEMA,
+            "shared" => shared(root),
+            "components" => components.to_h { |name, klass, file| [name, entry(klass, file:, names:, root:)] }
+          }
+        end
+
+        def generate(root: ROOT)
+          require "json"
+
+          "#{JSON.pretty_generate(build(root:))}\n"
+        end
+
+        def write(path = MANIFEST_PATH, root: ROOT)
+          json = generate(root:)
+          File.write(path, json) unless File.exist?(path) && File.read(path) == json
+          path
+        end
+
+        def entry(klass, file:, names:, root:)
+          source = File.read(file)
+          name = klass.component_class&.to_s
+          modifiers = modifier_classes(klass)
+          {
+            "class" => klass.name,
+            "name" => name,
+            "files" => [file.delete_prefix("#{root}/")],
+            "depends_on" => ((Lexer.constants(source) & names) - [short_name(klass)]).sort,
+            "modifiers" => modifiers,
+            "classes" => ([name, *modifiers].compact | Candidate.tokens(Lexer.strings(source).join(" "))).sort
+          }
+        end
+
+        private
+
+        # The gem's own components, by short name: a DaisyUI:: class defined
+        # in a file under lib/daisy_ui (not one a spec or an app defined).
+        def gem_components(lib)
+          ClassMerge::DaisyGroups.gem_components.filter_map do |klass|
+            file = Object.const_source_location(klass.name)&.first
+            [short_name(klass), klass, file] if file&.start_with?("#{lib}/")
+          end.sort_by(&:first)
+        end
+
+        def shared(root)
+          source = File.read(File.join(root, SHARED_FILE))
+          { "files" => [SHARED_FILE], "classes" => Candidate.tokens(Lexer.strings(source).join(" ")).uniq.sort }
+        end
+
+        def modifier_classes(klass)
+          classes = (klass.modifiers || {}).values.flat_map { |value| value.to_s.split }.uniq.sort
+          invalid = classes.reject { |token| Candidate.valid?(token) }
+          return classes if invalid.empty?
+
+          raise ArgumentError, "#{klass.name} registers #{invalid.map(&:inspect).join(', ')}, " \
+                               "which Tailwind cannot read from @source inline(…)"
+        end
+
+        def short_name(klass) = klass.name.split("::").last
+      end
+    end
+  end
+end