hanami_icons 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3afa33bc73c5af3cbd69a0e5fc7a9417c608b6173ea4e1ab0ceb101220af122
-  data.tar.gz: 3409501c85d83eee1d8871251d58012f89552b56bd00450918ef62ec0c3bd080
+  metadata.gz: 2b676ab621f60364217f28420be21eec51a36c4b7128ae562d271b8941f4134b
+  data.tar.gz: fb4ec56edaf60459102657f6ba811c1c9f322bbc28af3107695a1f7a81225112
 SHA512:
-  metadata.gz: 653d92e5ca0206d4a8ddd09d6b8ea393078e66f4850c8c8b1be4d390daf2cbac44f514c64556b3a54a0ca774b6140554963d7428911e82554aa6d950d2bfd080
-  data.tar.gz: f7f93a4158c3817630bb28563267807a66a58cf2c3bf7fd5d2381724f41a0127349f897c8431ee951bdc4b356f9d1b9cd60cde4cd7c5406bafdddde04af9211e
+  metadata.gz: a5513690d48a3ad7a1fa303c314873d869efaa1332fb96cb2d1c539f04eb05f8cb382bbf239deab010c9bb6884d494e92bc38b098761a8d30f01f05b768c1d63
+  data.tar.gz: 9c681679074b35d827f28af8fbb3ec50b78c38ee0cf51531a64369511ce664efbc0aaedfa01c97fcaff6c96283207890fc26ac712d14b969a3a14c7ed6bc285c

data/README.md

@@ -1,6 +1,6 @@
 # Hanami Icons
 
-Add any icon library to a Hanami app. Hanami Icons has first-party support for a [handful of libraries](#first-party-libraries). It is library agnostic so it can be used with any icon library using the same interface. Hanami Icons is a Hanami gem for the [Icons Ruby gem](https://github.com/Rails-Designer/icons).
+Add any icon library to a Hanami app. Hanami Icons has first-party support for [several libraries](#first-party-libraries) and one interface for all of them. It is a Hanami wrapper for the [Icons Ruby gem](https://github.com/Rails-Designer/icons).
 
 ```erb
 # Using the default icon library
@@ -10,68 +10,72 @@ Add any icon library to a Hanami app. Hanami Icons has first-party support for a
 <%== icon "apple", library: "simple_icons", class: "text-black" %>
 ```
 
-The icons are sourced directly from their respective GitHub repositories via the [Icons](https://github.com/Rails-Designer/icons) gem, ensuring Hanami Icons remain lightweight.
+The [Icons](https://github.com/Rails-Designer/icons) gem reads icons from their source repositories, so Hanami Icons stays small.
 
 **Sponsored By [Rails Designer](https://railsdesigner.com/)**
 
 ## Install
 
-Add the gem:
+Hanami loads CLI extensions from the `:cli` Bundler group. The view helpers also need the gem at runtime. Add the gem to both groups:
 
-```bash
-bundle add hanami_icons
+```ruby
+gem "hanami_icons", group: [:default, :cli]
 ```
 
-Install, choosing one of the supported libraries:
+Then run:
 
 ```bash
-hanami generate icons --library=heroicons
+bundle install
 ```
 
-**Example**
+Generate the provider and sync a library:
 
 ```bash
 hanami generate icons --library=heroicons
+```
 
-# Or multiple at once
+More examples:
+
+```bash
+# Multiple libraries
 hanami generate icons --libraries=heroicons lucide
 
-# Or only specific variants
+# Selected variants only
 hanami generate icons --library=heroicons --variants solid outline
 ```
 
-This creates `config/providers/icons.rb`, registers the provider with the app container and adds the view helpers into `app/views/helpers.rb`.
+The command creates `config/providers/icons.rb`, registers the `icons` provider, and adds the helpers to `app/views/helpers.rb`.
 
 ## Usage
 
 ```ruby
-# Uses the default library and variant defined in config/providers/icons.rb
+# Default library and variant from config/providers/icons.rb
 icon "check"
 
-# Use another variant
+# Another variant
 icon "check", variant: "solid"
 
-# Set library explicitly
+# Explicit library
 icon "check", library: "heroicons"
 
-# Add CSS
+# CSS class
 icon "check", class: "text-green-500"
 
-# Add data attributes
+# Data attributes
 icon "check", data: { controller: "swap" }
 
-# Set the stroke-width
+# Stroke width
 icon "check", stroke_width: 2
 
-# Base64-encoded data URI
+# Base64 data URI
 encoded_icon "check"
 ```
 
-The helpers return `Hanami::View::HTML::SafeString`, so they are safe to output in templates (`<%== … %>` or `&= …`).
+The helpers return `Hanami::View::HTML::SafeString`. Use `<%== %>` in ERB or `==` in Slim.
 
 ## Sprites
 
-Hanami Icons supports SVG sprites for improved performance. Instead of inlining each icon's full SVG, sprite icons reference a shared set of `<symbol>` definitions via `<use href="…">`.
+A sprite references shared `<symbol>` definitions with `<use href="…">`. Use a sprite when a page shows many icons.
 
 ### Configuration
 
@@ -81,13 +85,13 @@ HanamiIcons.configure do |config|
   config.default_library = "heroicons"
   config.default_variant = "outline"
 
-  # Where `sprite_icon` references symbols. Set to nil to use inline mode (`<%== icons_sprite %>` in layout).
+  # URL for `sprite_icon`. Set to nil for an inline sprite.
   config.default_sprite_location = "/sprite.svg"
 
-  # Set to true to validate that referenced icons exist on disk
+  # Check that referenced icons exist on disk.
   config.validate_sprite_icons = false
 
-  # Define which icons to include in the sprite
+  # Icons to include in the sprite.
   config.sprite = {
     heroicons: {
       outline: %w[check chevron-down menu search x],
@@ -99,24 +103,26 @@ end
 
 ### External sprite
 
-Generate a static sprite file and reference it with `sprite_icon`:
+Generate a sprite file:
 
 ```bash
 hanami generate icons:sprite
 ```
 
+Then reference it:
+
 ```erb
 <%== sprite_icon "check" %>
-<%# renders: <svg><use href="/sprite.svg#heroicons_outline_check"></use></svg> %>
+<%# => <svg><use href="/sprite.svg#heroicons_outline_check"></use></svg> %>
 ```
 
-Point at a precompiled file or a CDN by changing the location:
+Use a CDN or a different file:
 
 ```ruby
 config.default_sprite_location = "https://cdn.example.com/sprite_icons.svg"
 ```
 
-Override per icon:
+Override the location for one icon:
 
 ```erb
 <%== sprite_icon "check", sprite_location: "/assets/sprites.svg" %>
@@ -124,7 +130,7 @@ Override per icon:
 
 ### Inline sprite
 
-Set the location to `nil` and embed the sprite directly in your layout:
+Set the location to `nil` and embed the sprite in your layout:
 
 ```ruby
 config.default_sprite_location = nil
@@ -140,7 +146,7 @@ config.default_sprite_location = nil
 </body>
 ```
 
-You can also generate a sprite for a specific set of icons:
+Build a sprite for selected icons:
 
 ```erb
 <%== icons_sprite ["check", "search"], library: "heroicons", variant: "outline" %>
@@ -148,46 +154,53 @@ You can also generate a sprite for a specific set of icons:
 
 ## Sync icons
 
-To sync all libraries, run:
+Sync every first-party library:
 
 ```bash
 hanami generate icons:sync
 ```
 
-To sync only a specific library, run:
+Sync one library:
 
 ```bash
 hanami generate icons:sync --library=heroicons
+```
 
-# Or multiple at once:
+Sync several libraries:
+
+```bash
 hanami generate icons:sync --libraries=heroicons lucide
 ```
 
-To sync only specific variants for a library:
+Sync selected variants:
 
 ```bash
 hanami generate icons:sync --library=heroicons --variants solid outline
 ```
 
+The `icons:sync` command runs before the app boots, so it does not load `config/providers/icons.rb`. It sees first-party libraries only.
+
 ## Custom icon libraries
 
-Hanami Icons pulls SVGs straight from the path `<icons_path>/<library_name>/<name>.svg`. No generator is required for custom icons. Configuration is optional and only used to define defaults.
+Hanami Icons reads SVGs from `<icons_path>/<library>/<name>.svg`. Libraries with variants add a variant directory, such as `<icons_path>/heroicons/outline/check.svg`.
 
-To add a custom library, create its directory and drop in your SVGs:
+Local libraries need no configuration. Create the directory and add SVGs:
 
 ```
 app/assets/svg/icons/simple_icons/apple.svg
 ```
 
-(alternatively, scaffold it with `hanami generate icons --library=simple_icons`, which creates the directory and adds `config.custom_library :simple_icons` in the provider.)
-
-Use them like any other library:
+Then use the library:
 
 ```ruby
 icon "apple", library: "simple_icons"
 ```
 
-To add a git source for syncing, edit the provider:
+To scaffold a custom library, run `hanami generate icons --library=simple_icons`. The command creates the directory and adds `config.custom_library :simple_icons` to the provider.
+
+### Git-sourced libraries
+
+Add the source to the provider:
 
 ```ruby
 HanamiIcons.configure do |config|
@@ -198,12 +211,14 @@ HanamiIcons.configure do |config|
 end
 ```
 
-Then sync:
+`icons:sync` cannot see this library because it does not load providers. Sync it in the app context:
 
 ```bash
-hanami generate icons:sync --library=my_icons
+bundle exec hanami run 'Icons::Sync.new(:my_icons).now'
 ```
 
+You can also run the same call in `hanami console`.
+
 ## First-party libraries
 
 - [Boxicons](https://railsdesigner.com/open-source/rails-icons/boxicons/) (1600+ icons)
@@ -221,7 +236,7 @@ hanami generate icons:sync --library=my_icons
 
 ## Contributing
 
-This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `bundle exec standardrb` before submitting pull requests. Run tests via `bundle exec rake`.
+This project uses [Standard](https://github.com/testdouble/standard) for Ruby formatting. Run `bundle exec standardrb` before you open a pull request. Run the tests with `bundle exec rake`.
 
 ## License
 

data/hanami_icons.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary = "Add any icon library to a Hanami app"
   spec.description = "Add any icon library to a Hanami app, from Heroicons, to Lucide to Tabler (and others). Hanami Icons is library-agnostic, so you can add any library while using the same interface."
-  spec.homepage = "https://railsdesigner.com/open-source/hanami-icons/"
+  spec.homepage = "https://railsdesigner.com/open-source/hanami_icons/"
   spec.license = "MIT"
 
   spec.metadata["homepage_uri"] = spec.homepage

data/lib/hanami_icons/cli/commands/generate/icons.rb

@@ -17,7 +17,7 @@ module HanamiIcons
           option :library, desc: "Choose a library"
           option :libraries, type: :array, default: [], desc: "Choose libraries"
           option :variants, type: :array, desc: "Only sync specific variants (e.g. solid outline)"
-          option :destination, type: :string, default: HanamiIcons.configuration.icons_path, desc: "Specify destination folder for icons"
+          option :destination, type: :string, desc: "Specify destination folder for icons"
           option :skip_sync, type: :boolean, default: false
 
           # @param library [String, nil]
@@ -28,7 +28,9 @@ module HanamiIcons
           #
           # @api public
           # @since 0.1.0
-          def call(library: nil, libraries: [], variants: nil, destination: HanamiIcons.configuration.icons_path, skip_sync: false, **)
+          def call(library: nil, libraries: [], variants: nil, destination: nil, skip_sync: false, **)
+            destination ||= HanamiIcons.configuration.icons_path
+
             run_initializer(library: library, libraries: libraries, variants: variants, destination: destination)
 
             if !skip_sync && selected_libraries(library, libraries).any?

data/lib/hanami_icons/cli/commands/generate/initializer.rb

@@ -18,7 +18,7 @@ module HanamiIcons
           option :library, desc: "Choose a library"
           option :libraries, type: :array, default: [], desc: "Choose libraries"
           option :variants, type: :array, desc: "Only sync specific variants (e.g. solid outline)"
-          option :destination, type: :string, default: HanamiIcons.configuration.icons_path, desc: "Specify destination folder for icons"
+          option :destination, type: :string, desc: "Specify destination folder for icons"
 
           PROVIDER = "config/providers/icons.rb"
           HELPERS = "app/views/helpers.rb"
@@ -31,7 +31,9 @@ module HanamiIcons
           #
           # @api public
           # @since 0.1.0
-          def call(library: nil, libraries: [], variants: nil, destination: HanamiIcons.configuration.icons_path, **)
+          def call(library: nil, libraries: [], variants: nil, destination: nil, **)
+            destination ||= HanamiIcons.configuration.icons_path
+
             copy_provider
 
             insert_default_configuration(selected_libraries(library, libraries).first)

data/lib/hanami_icons/cli/commands/generate/sprite.rb

@@ -20,6 +20,8 @@ module HanamiIcons
           # @api public
           # @since 0.1.0
           def call(output: "public/sprite.svg", **)
+            HanamiIcons.configuration
+
             fs.mkdir(File.dirname(output))
             fs.write(output, ::Icons::Sprite.new.svg)
 

data/lib/hanami_icons/cli/commands/generate/sync.rb

@@ -24,6 +24,8 @@ module HanamiIcons
           # @api public
           # @since 0.1.0
           def call(library: nil, libraries: [], variants: nil, **)
+            HanamiIcons.configuration
+
             selected_libraries(library, libraries).each do |name|
               ::Icons::Sync.new(name, variants: variants&.map(&:to_sym)).now
             end

data/lib/hanami_icons/version.rb

@@ -1,3 +1,3 @@
 module HanamiIcons
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/hanami_icons.rb

@@ -27,16 +27,25 @@ module HanamiIcons
   class << self
     # @yield [config] Yields the Icons configuration
     # @yieldparam config [Icons::Configuration]
+    # @return [Icons::Configuration]
     #
     # @api public
     # @since 0.1.0
-    def configure(&block) = Icons.configure(&block)
+    def configure(&block)
+      Icons.configure(&block)
+
+      Icons.configuration
+    end
 
     # @return [Icons::Configuration]
     #
     # @api public
     # @since 0.1.0
-    def configuration = Icons.config
+    def configuration
+      Icons.configure {} unless Icons.configuration
+
+      Icons.configuration
+    end
 
     alias_method :config, :configuration
 
@@ -45,12 +54,16 @@ module HanamiIcons
     # @api public
     # @since 0.1.0
     def libraries = Icons.libraries
-  end
 
-  if Hanami::CLI.within_hanami_app?
-    Hanami::CLI.register "generate icons", CLI::Commands::Generate::Icons
-    Hanami::CLI.register "generate icons:initializer", CLI::Commands::Generate::Initializer
-    Hanami::CLI.register "generate icons:sync", CLI::Commands::Generate::Sync
-    Hanami::CLI.register "generate icons:sprite", CLI::Commands::Generate::Sprite
+    # @api private
+    # @since 0.1.0
+    def register_cli_commands!
+      Hanami::CLI.register "generate icons", CLI::Commands::Generate::Icons
+      Hanami::CLI.register "generate icons:initializer", CLI::Commands::Generate::Initializer
+      Hanami::CLI.register "generate icons:sync", CLI::Commands::Generate::Sync
+      Hanami::CLI.register "generate icons:sprite", CLI::Commands::Generate::Sprite
+    end
   end
+
+  register_cli_commands! if Hanami::CLI.within_hanami_app?
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hanami_icons
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Rails Designer
@@ -87,15 +87,15 @@ files:
 - lib/hanami_icons/helpers/icon_helper.rb
 - lib/hanami_icons/helpers/sprite_helper.rb
 - lib/hanami_icons/version.rb
-homepage: https://railsdesigner.com/open-source/hanami-icons/
+homepage: https://railsdesigner.com/open-source/hanami_icons/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://railsdesigner.com/open-source/hanami-icons/
+  homepage_uri: https://railsdesigner.com/open-source/hanami_icons/
   source_code_uri: https://github.com/Rails-Designer/hanami_icons
   changelog_uri: https://github.com/Rails-Designer/hanami_icons/releases
   bug_tracker_uri: https://github.com/Rails-Designer/hanami_icons/issues
-  documentation_uri: https://railsdesigner.com/open-source/hanami-icons/
+  documentation_uri: https://railsdesigner.com/open-source/hanami_icons/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: