Skip to content

feat(icon): make the chrome icon library configurable via DocsKit.configuration.icon_library - #6

Merged
mhenrixon merged 1 commit into
mainfrom
feat/configurable-icon-library
Jul 2, 2026
Merged

feat(icon): make the chrome icon library configurable via DocsKit.configuration.icon_library#6
mhenrixon merged 1 commit into
mainfrom
feat/configurable-icon-library

Conversation

@mhenrixon

Copy link
Copy Markdown
Collaborator

Problem

DocsUI::Icon renders the docs chrome's lucide icon names (menu, search, file-code, list, info, palette, lightbulb, triangle-alert, file-text, ...) but resolved them against RailsIcons.configuration.default_library.

On a host app whose default_library is not lucide (e.g. phosphor or heroicons), those lucide names don't exist in the configured library, so every chrome icon raises Icons::IconNotFound in development. The host app couldn't fix this without flipping its global RailsIcons default — which it shouldn't have to do just to render docs-kit's chrome.

Fix

Add a DocsKit.configuration.icon_library config option (default "lucide", matching the lucide icon names docs-kit ships). DocsUI::Icon#rails_icons_library now reads it, falling back to the host app's RailsIcons.configuration.default_library:

def rails_icons_library
  DocsKit.configuration.icon_library || ::RailsIcons.configuration.default_library
rescue StandardError
  nil
end
  • Zero-config, backwards compatible — the default is "lucide", and the icon names docs-kit ships are lucide names, so existing lucide-default apps are unaffected.
  • Independent of the host's global default — a phosphor/heroicons app leaves icon_library at "lucide" and the chrome keeps rendering, without changing its own default_library.
  • Escape hatch — set icon_library to nil to restore the old defer-to-host behavior.

This follows the project invariant that site-specific values live on DocsKit.configuration with a sensible default.

Test plan

New specs (written first, RED → GREEN):

  • spec/docs_kit/configuration_spec.rb#icon_library defaults to "lucide"; overridable via DocsKit.configure { |c| c.icon_library = "phosphor" }.
  • spec/docs_ui/icon_spec.rb#rails_icons_library:
    • returns the configured icon_library when set (the || short-circuits, so it never touches RailsIcons — the representative path for a non-lucide host);
    • falls back to RailsIcons.configuration.default_library when icon_library is nil (RailsIcons stubbed in — it's a Railtie gem, absent from the isolated suite);
    • degrades to nil when RailsIcons isn't loaded.

Verification (local — this repo has no PR CI, only a release-triggered deploy workflow):

  • bundle exec rspec55 examples, 0 failures
  • bundle exec rubocop lib app spec32 files, no offenses

Closes #3

…figuration.icon_library

Summary
-------
DocsUI::Icon rendered the docs chrome's lucide icons (menu, search, file-code,
...) against RailsIcons.configuration.default_library. On a host app whose
default_library is non-lucide (phosphor, heroicons), those lucide names don't
exist, raising Icons::IconNotFound in development — and an app couldn't flip its
global default just for the docs chrome.

This adds a DocsKit.configuration.icon_library knob (default "lucide", matching
the icon names docs-kit ships). DocsUI::Icon#rails_icons_library now reads it and
falls back to the host's RailsIcons default_library:

    DocsKit.configuration.icon_library || ::RailsIcons.configuration.default_library

Zero-config behavior is unchanged for lucide-default apps; any app can now pin
the chrome to lucide without touching its global default. Setting icon_library
to nil restores the old defer-to-host behavior.

Test Coverage
-------------
- spec/docs_kit/configuration_spec.rb — #icon_library defaults to "lucide" and
  is overridable via DocsKit.configure.
- spec/docs_ui/icon_spec.rb — #rails_icons_library returns the configured
  icon_library (the `||` short-circuits, so it never touches RailsIcons), falls
  back to RailsIcons.configuration.default_library when icon_library is nil (with
  RailsIcons stubbed in), and degrades to nil when RailsIcons is absent.

Verification
------------
- [x] bundle exec rspec — 55 examples, 0 failures
- [x] bundle exec rubocop (lib app spec) — 32 files, no offenses
- [x] Backwards compatible: default "lucide" keeps existing lucide apps working
@mhenrixon mhenrixon self-assigned this Jul 2, 2026
@mhenrixon mhenrixon added the enhancement New feature or request label Jul 2, 2026
@mhenrixon
mhenrixon merged commit bdb8aae into main Jul 2, 2026
@mhenrixon
mhenrixon deleted the feat/configurable-icon-library branch July 4, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make DocsUI::Icon's icon library configurable (currently hardcoded to RailsIcons default_library)

1 participant