its-swiss 0.1.0

data/lib/generators/its_swiss/install/install_generator.rb

@@ -0,0 +1,70 @@
+require "rails/generators/base"
+
+module ItsSwiss
+  module Generators
+    # Four things, each of them easy to get wrong by hand and quiet when it is
+    # wrong. Everything else the library does is a gem dependency and needs no
+    # generator at all: Propshaft finds the stylesheets, and the engine pins
+    # its own JavaScript so that upgrading the gem is enough to get the new
+    # file.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Fills in the slots its-swiss leaves for an application: the accent, the typeface, the grid."
+
+      def create_theme_stylesheet
+        template "theme.css", "app/assets/stylesheets/theme.css"
+      end
+
+      # An application that has already chosen a layout has chosen it.
+      def render_through_the_shell
+        controller = "app/controllers/application_controller.rb"
+        return say_status(:skip, "#{controller} not found", :yellow) unless exists?(controller)
+
+        contents = read(controller)
+        return say_status(:skip, "#{controller} already chooses a layout", :yellow) if contents.match?(/^\s*layout\s/)
+
+        inject_into_class controller, "ApplicationController", %(  layout "its_swiss/shell"\n)
+      end
+
+      # Development only, and the controller refuses it a second time: the
+      # specimen names every component the library has, and a route is a line
+      # in a file someone can move.
+      def mount_the_specimen
+        routes = "config/routes.rb"
+        return say_status(:skip, "#{routes} not found", :yellow) unless exists?(routes)
+        return say_status(:skip, "the specimen is already mounted", :yellow) if read(routes).include?("ItsSwiss::Engine")
+
+        inject_into_file routes, after: /Rails\.application\.routes\.draw do\n/ do
+          <<~RUBY.indent(2)
+            if Rails.env.development?
+              mount ItsSwiss::Engine => "/its-swiss"
+            end
+
+          RUBY
+        end
+      end
+
+      def say_what_is_left
+        say <<~TEXT
+
+          its-swiss is installed. What is left is yours:
+
+            app/assets/stylesheets/theme.css   the accent, the typeface, the grid
+            /its-swiss/specimen                every component, rendered twice
+
+          The library ships no typeface and no palette. Set --accent to one
+          colour and read the specimen with it unset: if the page still works,
+          the value scale is doing the work.
+        TEXT
+      end
+      private
+        # Thor writes relative to destination_root; reading has to as well, or
+        # the guards above interrogate whatever directory the generator was
+        # invoked from.
+        def exists?(path) = File.exist?(File.expand_path(path, destination_root))
+
+        def read(path) = File.read(File.expand_path(path, destination_root))
+    end
+  end
+end

data/lib/generators/its_swiss/install/templates/theme.css

@@ -0,0 +1,44 @@
+/* What this application fills in.
+ *
+ * Unlayered on purpose. Everything its-swiss ships is inside a cascade layer,
+ * and an unlayered rule beats every layered one whatever its specificity — so
+ * this file wins without having to out-specify the library or reach for
+ * !important, and the grid and the domain components below it win too.
+ */
+
+:root {
+  /* --- The accent --------------------------------------------------------
+     State and emphasis only: the current destination, focus, a link, the one
+     primary action, the moment before something cannot be undone. Never a
+     filled area for its own sake.
+
+     Delete this line and read the app. If it still works, the value scale is
+     doing the work, which is the point. */
+  --accent: oklch(57.7% 0.234 28);
+  --accent-ink: var(--paper);
+
+  /* --- The typeface ------------------------------------------------------
+     The library ships none. Declare an @font-face below and name it here, or
+     leave this out and take the grotesque stack the library falls back to. */
+  /* --font-family: "Your Face", ui-sans-serif, system-ui, sans-serif; */
+
+  /* --- The value scale ---------------------------------------------------
+     Neutral as it ships. These two turn the whole ladder together: a small
+     chroma at a yellow-green hue gives the warm grays of a printed page. */
+  /* --value-chroma: 0.006; */
+  /* --value-hue: 95; */
+
+  /* --- The grid ----------------------------------------------------------
+     How many fields this problem has. Six divides into halves and thirds and
+     is where the library starts; change it here once the pages have said what
+     they need, and every width in the app re-proportions. */
+  --columns: 6;
+  --gutter: 1.5rem;
+  --baseline: 0.5rem;
+}
+
+/* The grid itself lives here, not in the gem: which blocks span which fields
+   is what this application looks like.
+
+   main.grid > .page-head { --span: 4; }
+*/

data/lib/its-swiss.rb

@@ -0,0 +1,3 @@
+# The gem is named with a hyphen and the library with an underscore, so
+# `gem "its-swiss"` finds something to require.
+require "its_swiss"

data/lib/its_swiss/engine.rb

@@ -0,0 +1,39 @@
+require "rails/engine"
+
+module ItsSwiss
+  # Isolated, so the specimen's routes and helpers cannot collide with the
+  # application's. The stylesheets are not isolated by anything — CSS has one
+  # global namespace and pretending otherwise would mean prefixing every
+  # class in the library.
+  class Engine < ::Rails::Engine
+    isolate_namespace ItsSwiss
+
+    # Propshaft picks up an engine's app/assets/stylesheets on its own. The
+    # JavaScript is not in that default set, and it is one file, so it is
+    # added here rather than left to the application to remember.
+    initializer "its_swiss.assets" do |app|
+      next unless app.config.respond_to?(:assets)
+
+      app.config.assets.paths << root.join("app/assets/javascripts")
+    end
+
+    # Pinned from the engine rather than written into the application's
+    # importmap by the generator: an application that upgrades the gem should
+    # get the new file without re-running a generator, and a pin it never
+    # wrote is a pin it cannot leave stale.
+    initializer "its_swiss.importmap", before: "importmap" do |app|
+      next unless app.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      # Reloading in development watches the pinned files for changes; a gem
+      # loaded from a path: dependency is being edited, so it is watched too.
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+
+    config.to_prepare do
+      ActiveSupport.on_load(:action_view) do
+        include ItsSwiss::ApplicationHelper
+      end
+    end
+  end
+end

data/lib/its_swiss/form_builder.rb

@@ -0,0 +1,140 @@
+module ItsSwiss
+  # One shape for every field: a label, a control, and — when there is
+  # something to say — a hint or the reason it was refused.
+  #
+  # Written by a builder rather than by hand because the parts that get left
+  # out by hand are the parts nobody sees missing. A label whose `for` does not
+  # match its input is a label that does not enlarge the target. A hint beside
+  # a control is a hint a screen reader never reaches. A refused field coloured
+  # by CSS alone is a refusal that only some readers get.
+  class FormBuilder < ActionView::Helpers::FormBuilder
+    # Everything that is a line of text under a rule. They differ only in the
+    # keyboard a phone puts up, which is not a difference the markup has.
+    TEXT_FIELDS = %i[
+      text_field email_field password_field number_field url_field
+      telephone_field phone_field search_field date_field time_field
+      datetime_field color_field text_area
+    ].freeze
+
+    TEXT_FIELDS.each do |control|
+      define_method(control) do |method, options = {}|
+        field(method, options) { |opts| super(method, opts) }
+      end
+    end
+
+    def select(method, choices = nil, options = {}, html_options = {}, &block)
+      field(method, html_options) do |opts|
+        super(method, choices, options, opts, &block)
+      end
+    end
+
+    def collection_select(method, collection, value_method, text_method, options = {}, html_options = {})
+      field(method, html_options) do |opts|
+        super(method, collection, value_method, text_method, options, opts)
+      end
+    end
+
+    # A checkbox and its label are a pair on one line — the label says what
+    # ticking it means, and reading that above an empty box says nothing.
+    def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
+      field(method, options, label_beside: true) do |opts|
+        super(method, opts, checked_value, unchecked_value)
+      end
+    end
+
+    def radio_button(method, tag_value, options = {})
+      field(method, options, label_beside: true, label_for_value: tag_value) do |opts|
+        super(method, tag_value, opts)
+      end
+    end
+
+    # A <button>, not an <input>: an input's label is an attribute, and the
+    # one thing this style asks of a button is that it be a box with words in
+    # it. Primary unless the caller says otherwise, because a form has one
+    # thing it is for.
+    def submit(value = nil, options = {})
+      value ||= submit_default_value
+      options = { class: "button button--primary" }.merge(options.symbolize_keys)
+
+      @template.tag.button(value, **options, type: "submit")
+    end
+
+    # The wrapper on its own, for a control the library does not know about.
+    def field(method, options = {}, label_beside: false, label_for_value: nil, &control)
+      options = options.symbolize_keys
+      hint, label_option = options.delete(:hint), options.delete(:label)
+      errors = errors_on(method)
+
+      ids = describers(method, hint, errors)
+      options[:"aria-describedby"] = ids.join(" ") if ids.any?
+      options[:"aria-invalid"] = "true" if errors.any?
+
+      label = rendered_label(method, label_option, label_for_value)
+      options[:"aria-label"] ||= default_label(method) if label.nil?
+      body = @template.capture { control.call(options) }
+      body = @template.tag.span(safe_join([ body, label ]), class: "choice") if label_beside && label
+
+      @template.tag.div(class: field_classes(errors)) do
+        safe_join([
+          (label unless label_beside),
+          body,
+          hint_tag(method, hint),
+          *errors.map.with_index { |message, index| error_tag(method, index, message) }
+        ].compact)
+      end
+    end
+
+    private
+      def field_classes(errors)
+        errors.any? ? "field field--invalid" : "field"
+      end
+
+      # `label: false` hides the label; it does not remove it. Something has to
+      # name the control, so the name moves onto the control itself.
+      def rendered_label(method, option, for_value)
+        return nil if option == false
+
+        label(method, option.is_a?(String) ? option : nil, value: for_value)
+      end
+
+      # A control whose label is hidden still needs a name, and aria-label is
+      # where it goes. Applied to the control rather than the wrapper because
+      # the wrapper is a div and names nothing.
+      def describers(method, hint, errors)
+        ids = []
+        ids << hint_id(method) if hint
+        errors.each_index { |index| ids << error_id(method, index) }
+        ids
+      end
+
+      def hint_tag(method, hint)
+        return nil unless hint
+
+        @template.tag.p(hint, class: "hint", id: hint_id(method))
+      end
+
+      def error_tag(method, index, message)
+        @template.tag.p(message, class: "field__error", id: error_id(method, index))
+      end
+
+      # What the label would have said, for a control whose label is hidden.
+      def default_label(method)
+        @object_name.to_s.camelize.safe_constantize&.human_attribute_name(method) ||
+          method.to_s.humanize
+      end
+
+      def hint_id(method) = "#{field_id(method)}_hint"
+
+      def error_id(method, index) = "#{field_id(method)}_error_#{index}"
+
+      # Full messages, so "cannot be blank" reads as a sentence about the
+      # field rather than as a fragment floating under it.
+      def errors_on(method)
+        return [] unless @object.respond_to?(:errors)
+
+        Array(@object.errors.full_messages_for(method))
+      end
+
+      def safe_join(parts) = @template.safe_join(parts)
+  end
+end

data/lib/its_swiss/version.rb

@@ -0,0 +1,3 @@
+module ItsSwiss
+  VERSION = "0.1.0"
+end

data/lib/its_swiss.rb

@@ -0,0 +1,46 @@
+require "its_swiss/version"
+require "its_swiss/engine" if defined?(Rails::Engine)
+
+module ItsSwiss
+  # Autoloaded rather than required: it subclasses ActionView's builder, which
+  # does not exist until Action View has loaded, and this file is read while
+  # the application is still assembling itself.
+  autoload :FormBuilder, "its_swiss/form_builder"
+
+  # The stylesheets, in the order their layers are declared. The gem's own
+  # layer order is fixed here rather than left to whoever writes the <link>
+  # tags: an application that loads type before tokens should still get the
+  # cascade the library was designed with.
+  #
+  # Every file states its own layer, so linking these six individually and
+  # linking the single its-swiss.css that imports them resolve identically.
+  STYLESHEETS = %w[ tokens reset type grid components transitions ].freeze
+
+  # The cascade layer everything the gem ships lives in. An application's own
+  # CSS is unlayered, and unlayered rules beat every layered one regardless of
+  # specificity — which is the boundary in the table made mechanical: the gem
+  # is a base, and the app's grid and domain components win without anyone
+  # having to count selectors or reach for !important.
+  LAYER = "its-swiss".freeze
+
+  class << self
+    # Where a consumer says which of the gem's slots it fills. Nothing here
+    # has a default the gem could reasonably pick for it.
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+
+  class Configuration
+    # The specimen is documentation and a regression fixture, not a page an
+    # application serves. It stays off unless the environment asks for it, so
+    # a route left mounted by accident cannot answer in production.
+    attr_writer :specimen
+
+    def specimen? = @specimen.nil? ? !!Rails.env.local? : @specimen
+  end
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: its-swiss
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bobby Meyer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
+- !ruby/object:Gem::Dependency
+  name: propshaft
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: |-
+  Tokens, reset, typography, grid primitives and components in the spirit of
+  the International Typographic Style, as plain CSS plus a Rails engine that
+  ships it. Monochrome by default: the value scale does the work and the one
+  accent is the consuming application's to set.
+email:
+- bobby@bobbymeyer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/javascripts/its_swiss/clipboard_controller.js
+- app/assets/stylesheets/its-swiss.css
+- app/assets/stylesheets/its_swiss/components.css
+- app/assets/stylesheets/its_swiss/grid.css
+- app/assets/stylesheets/its_swiss/reset.css
+- app/assets/stylesheets/its_swiss/specimen.css
+- app/assets/stylesheets/its_swiss/tokens.css
+- app/assets/stylesheets/its_swiss/transitions.css
+- app/assets/stylesheets/its_swiss/type.css
+- app/controllers/its_swiss/specimen_controller.rb
+- app/helpers/its_swiss/application_helper.rb
+- app/views/its_swiss/shared/_errors.html.erb
+- app/views/its_swiss/shared/_flash.html.erb
+- app/views/its_swiss/shared/_masthead.html.erb
+- app/views/its_swiss/shared/_pagination.html.erb
+- app/views/its_swiss/specimen/_buttons.html.erb
+- app/views/its_swiss/specimen/_footer.html.erb
+- app/views/its_swiss/specimen/_form.html.erb
+- app/views/its_swiss/specimen/_grid.html.erb
+- app/views/its_swiss/specimen/_masthead.html.erb
+- app/views/its_swiss/specimen/_messages.html.erb
+- app/views/its_swiss/specimen/_pagination.html.erb
+- app/views/its_swiss/specimen/_pairs.html.erb
+- app/views/its_swiss/specimen/_table.html.erb
+- app/views/its_swiss/specimen/_take.html.erb
+- app/views/its_swiss/specimen/_type.html.erb
+- app/views/its_swiss/specimen/_values.html.erb
+- app/views/its_swiss/specimen/show.html.erb
+- app/views/layouts/its_swiss/shell.html.erb
+- config/importmap.rb
+- config/routes.rb
+- lib/generators/its_swiss/install/install_generator.rb
+- lib/generators/its_swiss/install/templates/theme.css
+- lib/its-swiss.rb
+- lib/its_swiss.rb
+- lib/its_swiss/engine.rb
+- lib/its_swiss/form_builder.rb
+- lib/its_swiss/version.rb
+homepage: https://github.com/bobbymeyer/its-swiss
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bobbymeyer/its-swiss
+  bug_tracker_uri: https://github.com/bobbymeyer/its-swiss/issues
+  changelog_uri: https://github.com/bobbymeyer/its-swiss/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Swiss typographic style for Rails applications.
+test_files: []