unmagic-components 0.1.0

data/app/assets/stylesheets/unmagic/components.css

@@ -0,0 +1,382 @@
+/* unmagic-components
+ *
+ * Plain CSS on purpose. Tailwind only generates classes it can see and it does
+ * not scan installed gems, so any utility written inside this gem's Ruby would
+ * silently render unstyled in a host app. Owning the CSS here also means the
+ * components work in an app that doesn't use Tailwind at all.
+ *
+ * Theming is one layer of custom properties. Every value falls back to a
+ * Tailwind palette default, so the components look right with no configuration;
+ * a host overrides by setting --unmagic-* wherever its own theme is defined:
+ *
+ *   :root {
+ *     --unmagic-surface: var(--surface);
+ *     --unmagic-border:  var(--border);
+ *   }
+ *
+ * Dark mode needs nothing here. Host tokens that already flip carry these with
+ * them, which is why this file declares no dark variant of its own and makes no
+ * assumption about how the host selects a theme.
+ */
+
+/* ------------------------------------------------------------------ Table */
+
+/* Content-sized by default, so a Markdown table wearing this class hugs its
+   content rather than stretching. table_tag adds the --full modifier, which is
+   what an index table wants. */
+.UnmagicTable {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+  background-color: var(--unmagic-surface, var(--color-white, #fff));
+  border: 1px solid var(--unmagic-border, var(--color-neutral-200, #e5e5e5));
+  border-radius: 0.75rem;
+  border-collapse: separate;
+  border-spacing: 0;
+  overflow: hidden;
+}
+
+.UnmagicTable--full {
+  width: 100%;
+}
+
+.UnmagicTable--fixed {
+  table-layout: fixed;
+}
+
+.UnmagicTable__caption {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+.UnmagicTable thead th {
+  padding: 0.75rem 1rem;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  font-weight: 600;
+  text-align: left;
+  white-space: nowrap;
+  color: var(--unmagic-text-2, var(--color-neutral-600, #525252));
+  background-color: var(--unmagic-surface-2, var(--color-neutral-50, #fafafa));
+  border-bottom: 1px solid var(--unmagic-border, var(--color-neutral-200, #e5e5e5));
+}
+
+.UnmagicTable tbody td {
+  padding: 0.75rem 1rem;
+  vertical-align: middle;
+  border-bottom: 1px solid var(--unmagic-border, var(--color-neutral-200, #e5e5e5));
+}
+
+/* The border rides on the cells rather than the row: with border-collapse
+   separate, a border set on a <tr> is not painted. */
+.UnmagicTable tbody tr:last-child > td {
+  border-bottom: 0;
+}
+
+.UnmagicTable tbody tr:hover > td {
+  background-color: var(--unmagic-hover, var(--color-neutral-50, #fafafa));
+}
+
+/* A row carrying a companion details row below it drops its bottom border, so
+   the pair reads as one row. */
+.UnmagicTable tbody tr.has-details > td {
+  border-bottom: 0;
+}
+
+.UnmagicTable tbody tr.UnmagicTable__details > td {
+  padding-top: 0;
+}
+
+.UnmagicTable .is-right {
+  text-align: right;
+}
+
+.UnmagicTable .is-center {
+  text-align: center;
+}
+
+.UnmagicTable .is-numeric {
+  font-variant-numeric: tabular-nums;
+}
+
+.UnmagicTable__sort {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  color: inherit;
+  text-decoration: none;
+}
+
+.UnmagicTable__sort:hover {
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+}
+
+/* --------------------------------------------------------------- Skeleton */
+
+.UnmagicSkeleton {
+  position: relative;
+  height: 1rem;
+  border-radius: 0.25rem;
+  overflow: hidden;
+  background-color: var(--unmagic-skeleton, var(--color-neutral-200, #e5e5e5));
+}
+
+.UnmagicSkeleton.is-right {
+  margin-left: auto;
+}
+
+/* The shimmer is a translated ::after so it stays on the compositor; the radius
+   and sizing stay on the element itself, which clips the band to the shape. */
+.UnmagicSkeleton::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background-image: linear-gradient(
+    90deg,
+    transparent,
+    var(--unmagic-skeleton-shimmer, rgb(255 255 255 / 0.7)),
+    transparent
+  );
+  transform: translateX(-100%);
+  animation: unmagic-skeleton-shimmer 1.5s ease-in-out infinite;
+}
+
+@keyframes unmagic-skeleton-shimmer {
+  100% {
+    transform: translateX(100%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .UnmagicSkeleton::after {
+    animation: none;
+  }
+}
+
+/* ------------------------------------------------------------ Empty state */
+
+.UnmagicEmptyState {
+  padding: 2rem;
+  text-align: center;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: var(--unmagic-text-3, var(--color-neutral-500, #737373));
+  border: 1px dashed var(--unmagic-border-strong, var(--color-neutral-300, #d4d4d4));
+  border-radius: 0.5rem;
+}
+
+/* ------------------------------------------------------------- Pagination */
+
+.UnmagicPagination {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  margin-top: 1.25rem;
+}
+
+.UnmagicPagination__link {
+  padding: 0.25rem 0.75rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+  text-decoration: none;
+  background-color: var(--unmagic-surface, var(--color-white, #fff));
+  border: 1px solid var(--unmagic-border-strong, var(--color-neutral-300, #d4d4d4));
+  border-radius: 0.375rem;
+}
+
+.UnmagicPagination__link:hover {
+  background-color: var(--unmagic-hover, var(--color-neutral-50, #fafafa));
+}
+
+.UnmagicPagination__link[aria-disabled="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+/* -------------------------------------------------------- Description list */
+
+.UnmagicDescriptionList {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 0.5rem 1.5rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+
+.UnmagicDescriptionList dt {
+  grid-column: 1;
+  color: var(--unmagic-text-2, var(--color-neutral-600, #525252));
+}
+
+.UnmagicDescriptionList dd {
+  grid-column: 2;
+  margin: 0;
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+}
+
+/* The stacked variant is a different layout, not a restyle of the inline one:
+   small caps labels above their values, in two columns once there is room. */
+.UnmagicDescriptionList--stacked {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 1.25rem 2rem;
+}
+
+@media (min-width: 40rem) {
+  .UnmagicDescriptionList--stacked {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .UnmagicDescriptionList--stacked > .is-full {
+    grid-column: span 2 / span 2;
+  }
+}
+
+.UnmagicDescriptionList--stacked dt {
+  grid-column: auto;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+  color: var(--unmagic-text-3, var(--color-neutral-400, #a3a3a3));
+}
+
+.UnmagicDescriptionList--stacked dd {
+  grid-column: auto;
+  margin-top: 0.25rem;
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+}
+
+/* ------------------------------------------------------------------- Forms */
+
+/* Structure only. What a control itself looks like is left to the host: apps
+   style inputs in incompatible ways — a class on every input, or a bare-element
+   rule — and picking one here would be wrong in the other. */
+
+.UnmagicField {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+  margin-bottom: 1rem;
+}
+
+.UnmagicField--in-row {
+  flex: 1 1 0%;
+  margin-bottom: 0;
+}
+
+.UnmagicField--inline {
+  margin-bottom: 0;
+}
+
+.UnmagicFieldGroup {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  margin-bottom: 1rem;
+}
+
+@media (min-width: 40rem) {
+  .UnmagicFieldGroup {
+    flex-direction: row;
+  }
+}
+
+.UnmagicFieldGroup--inline {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.UnmagicLabel {
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--unmagic-text-2, var(--color-neutral-600, #525252));
+}
+
+.UnmagicLabel__required {
+  color: var(--unmagic-bad, var(--color-red-500, #ef4444));
+}
+
+.UnmagicHint {
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--unmagic-text-3, var(--color-neutral-500, #737373));
+}
+
+.UnmagicError {
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--unmagic-bad, var(--color-red-600, #dc2626));
+}
+
+.UnmagicFormErrors {
+  margin-bottom: 1rem;
+  padding: 0.5rem 0.75rem;
+  font-size: 0.875rem;
+  border-radius: 0.375rem;
+  color: var(--unmagic-bad, var(--color-red-700, #b91c1c));
+  border: 1px solid var(--unmagic-bad-border, var(--color-red-200, #fecaca));
+  background-color: var(--unmagic-bad-surface, var(--color-red-50, #fef2f2));
+}
+
+.UnmagicCheckField {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  cursor: pointer;
+}
+
+.UnmagicCheckField__text {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.UnmagicCheckField__label {
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+}
+
+.UnmagicCheckList {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.UnmagicCheckList--inline {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem 1.5rem;
+}
+
+/* A plain, unobtrusive button, so an unconfigured form still has one that looks
+   deliberate. Most apps point config.submit_class at their own button helper. */
+.UnmagicButton {
+  padding: 0.375rem 0.875rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  border-radius: 0.375rem;
+  cursor: pointer;
+  border: 1px solid var(--unmagic-border-strong, var(--color-neutral-300, #d4d4d4));
+  background-color: var(--unmagic-surface, var(--color-white, #fff));
+  color: var(--unmagic-text, var(--color-neutral-900, #171717));
+}
+
+.UnmagicButton--primary {
+  border-color: transparent;
+  background-color: var(--unmagic-accent, var(--color-neutral-900, #171717));
+  color: var(--unmagic-on-accent, var(--color-white, #fff));
+}

data/config/importmap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+pin "unmagic/components/upsert", to: "unmagic/components/upsert.js", preload: true

data/lib/unmagic/components/action_view_helpers.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # Mixed into ActionView by the engine, so every template can call these.
+    module ActionViewHelpers
+      # Declarative tables in the spirit of form_for: table_for yields a builder
+      # that collects column definitions, then renders the table chrome — the
+      # card, header (with optional sort links), empty state, and pagination — so
+      # index views only describe their cells.
+      #
+      #   <%= table_for @users do |table| %>
+      #     <% table.empty "No team members yet." %>
+      #     <% table.column "Name" do |user| %>
+      #       <%= user.name %>
+      #     <% end %>
+      #     <% table.column "Created", sort: :created_at, direction: :desc do |user| %>
+      #       <%= user.created_at.to_fs(:short) %>
+      #     <% end %>
+      #     <% table.column "Actions", align: :right do |user| %>
+      #       <%= button_to "Remove", user_path(user), method: :delete %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # Linking to a record is the view's job — render the cell's primary text as
+      # a link.
+      #
+      # sort:  a column with sort: renders its header as a link that toggles
+      #        ?sort/?direction; direction: declares the column's first direction.
+      #        Pass sorted_by:/sort_direction: when the applied default isn't in
+      #        params, and sort_url: ->(key, direction) { url } when sorting is
+      #        carried by other params (e.g. nested search params).
+      # defer: true wraps the table in a turbo frame pointing back at the current
+      #        URL: the initial request renders only a skeleton — the collection
+      #        is never touched — and the frame then fetches the real rows.
+      #        Sorting and paging navigate within the frame, advancing the URL.
+      #        Pairs with a lazy collection so the skeleton render costs nothing;
+      #        the action needs no special casing.
+      # width: pins a column through a <colgroup>, switching the table to a fixed
+      #        layout. A CSS length ("40%", "170px") rides on the <col> as a
+      #        style; anything else is used as a class name, so a Tailwind host
+      #        can pass "w-[40%]". Give every column of a deferred table a width
+      #        so the skeleton and the rows that replace it lay out identically.
+      #
+      # Empty states come in two flavours. table.empty is the blank slate for a
+      # genuinely empty dataset; table.no_results is shown instead when a
+      # search/filter matched nothing. The table tells them apart on its own: a
+      # collection reporting filtered? picks no_results automatically. A plain
+      # relation or array isn't filterable, so it always uses empty.
+      #
+      # Pagination renders through the configured pagination seam, from whatever
+      # the configured pagy_for seam resolves (paginate: false to suppress, or
+      # pass a pagy object directly).
+      #
+      # Any other option rides on the <table> itself — class:, data:, aria — so a
+      # view can space or annotate it without a wrapper. `id:` is the exception:
+      # it names the deferred turbo frame, not the table.
+      def table_for(collection, defer: false, id: nil, paginate: true, columns: nil, **options, &block)
+        builder = Components::Table.new(self, collection, **options)
+        render(columns, table: builder) if columns
+        capture(builder, &block) if block
+
+        pagy = table_pagy_for(collection, paginate)
+
+        if defer
+          frame_id = id || "#{controller.controller_name}_table"
+
+          if turbo_frame_request_id == frame_id
+            turbo_frame_tag frame_id, target: "_top" do
+              builder.render(pagy: pagy, turbo_frame: frame_id)
+            end
+          else
+            turbo_frame_tag frame_id, src: request.original_url, target: "_top" do
+              builder.skeleton
+            end
+          end
+        else
+          builder.render(pagy: pagy)
+        end
+      end
+
+      # The single <tr> a table would render for one record — what a Turbo Stream
+      # broadcast upserts into a live table's tbody.
+      #
+      # The columns have to be declared somewhere both the table and the broadcast
+      # can reach, so they move into a partial that takes a `table` local and does
+      # nothing but declare them:
+      #
+      #   <%# tasks/_columns.html.erb %>
+      #   <% table.column "Kind", width: "30%" do |task| %>
+      #     <%= link_to task.kind, task %>
+      #   <% end %>
+      #
+      # The page renders the table with them:
+      #
+      #   <%= table_for @tasks, columns: "tasks/columns", rows_id: "task_rows" %>
+      #
+      # and a broadcast renders one row with the same file, so the two can never
+      # drift:
+      #
+      #   <%# tasks/_row.html.erb %>
+      #   <%= row_for task, columns: "tasks/columns" %>
+      #
+      #   broadcast_action_to "tasks", action: :upsert, target: "task_rows",
+      #     partial: "tasks/row", locals: { task: self }
+      #
+      # Pass the same row_class: the table uses so a broadcast row matches. The
+      # companion details row is not included — a stream action carries one element.
+      def row_for(record, columns:, **options)
+        builder = Components::Table.new(self, [ record ], **options)
+        render(columns, table: builder)
+        builder.row(record)
+      end
+
+      # Renders the same table chrome from plain data, so a static table gets the
+      # same look without table_for's record/sort/pagination machinery.
+      #
+      #   <%= table_tag [ "Name", "Score" ], [ [ "Ann", 42 ], [ "Bob", 7 ] ], aligns: [ nil, :right ] %>
+      #
+      # headers and each row are arrays of cells. A cell is a value (rendered
+      # as-is — pass a safe string for markup) or a { content:, **attrs } hash to
+      # set attributes on its th/td. A row may itself be a { cells:, **attrs }
+      # hash to set attributes on its <tr>. aligns and widths are per-column, and
+      # rows_id puts an id on the <tbody>. Pass headers: nil (or []) to omit the
+      # thead.
+      def table_tag(headers, rows, **options)
+        Components::TableTag.new(self, headers, rows, **options).render
+      end
+
+      # Declarative <dl> detail lists in the spirit of table_for.
+      #
+      #   <%= detail_list do |list| %>
+      #     <% list.item "Created", candidate.created_at.to_fs(:short) %>
+      #     <% list.item "Salary", candidate.salary_expectation %>
+      #   <% end %>
+      #
+      #   <%= detail_list variant: :stacked do |list| %>
+      #     <% list.item "Client ID", @application.uid, class: "font-mono" %>
+      #     <% list.item "Redirect URIs", span: :full do %>
+      #       ...
+      #     <% end %>
+      #   <% end %>
+      #
+      # variant: :inline (default) lays labels beside values in a two-column grid;
+      # :stacked puts small uppercase labels above values, two columns on wide
+      # screens. class: adds to the <dl>.
+      #
+      # A blank value — or a block that captures nothing — renders as an em dash.
+      # Pass a block for markup-heavy values. An item's class: adds to its <dd>;
+      # span: :full stretches a stacked item across both columns.
+      def detail_list(variant: :inline, **options, &block)
+        builder = Components::DetailList.new(self, variant: variant, **options)
+        capture(builder, &block)
+        builder.render
+      end
+
+      private
+
+      def table_pagy_for(collection, paginate)
+        case paginate
+        when true then Components.configuration.pagy_for.call(self, collection)
+        when false, nil then nil
+        else paginate
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # The seams the components render through. Each is a callable, and each has a
+    # working default, so the gem depends on no host helper and on no pagination
+    # library. An app that already owns these concerns points them at its own
+    # versions in an initializer.
+    class Configuration
+      attr_writer :empty_state, :pagination, :pagy_for, :submit_class
+
+      # Renders a table's blank slate. Called with (view, content), where content
+      # is already-captured markup or a plain string.
+      def empty_state
+        @empty_state ||= Renderers::EmptyState.default
+      end
+
+      # Renders a table's pager. Called with (view, pagy:, turbo_frame:).
+      def pagination
+        @pagination ||= Renderers::Pagination.default
+      end
+
+      # Resolves the pagy object a table should page with. Called with
+      # (view, collection); returning nil suppresses the pager.
+      def pagy_for
+        @pagy_for ||= Renderers::Pagination.default_pagy_for
+      end
+
+      # The classes on a form's submit button. Called with (view, variant), so an
+      # app can hand back whatever its own button helper produces.
+      def submit_class
+        @submit_class ||= ->(_view, variant) { "UnmagicButton UnmagicButton--#{variant}" }
+      end
+    end
+  end
+end

data/lib/unmagic/components/detail_list/item.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    class DetailList
+      class Item
+        attr_reader :label, :block
+
+        def initialize(label:, value:, block:, span: nil, **options)
+          @label = label
+          @value = value
+          @block = block
+          @span = span
+          @classes = options[:class]
+        end
+
+        def full_span? = @span == :full
+
+        # A blank value renders as an em dash, so call sites don't need their own
+        # `.presence || "—"`.
+        def value
+          @value.presence || "—"
+        end
+
+        def dd_classes(base = nil)
+          [ base, @classes ].compact.presence&.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/detail_list.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # Collects the items a `detail_list` block declares and renders them as a
+    # <dl>. See ActionViewHelpers#detail_list for the public API.
+    class DetailList
+      VARIANTS = %i[inline stacked].freeze
+
+      def initialize(view, variant:, **options)
+        unless VARIANTS.include?(variant)
+          raise ArgumentError, "unknown detail_list variant #{variant.inspect} (expected one of #{VARIANTS.inspect})"
+        end
+
+        @view = view
+        @variant = variant
+        @classes = options[:class]
+        @items = []
+      end
+
+      def item(label, value = nil, **options, &block)
+        @items << Item.new(label: label, value: value, block: block, **options)
+        nil
+      end
+
+      def render
+        classes = view.class_names(
+          "UnmagicDescriptionList",
+          { "UnmagicDescriptionList--stacked" => stacked? },
+          @classes,
+        )
+
+        tag.dl class: classes do
+          safe_join @items.map { |item| stacked? ? stacked_item(item) : inline_item(item) }
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def stacked? = @variant == :stacked
+
+      def inline_item(item)
+        safe_join [ tag.dt(item.label), tag.dd(value(item), class: item.dd_classes) ]
+      end
+
+      def stacked_item(item)
+        tag.div class: ("is-full" if item.full_span?) do
+          safe_join [ tag.dt(item.label), tag.dd(value(item), class: item.dd_classes) ]
+        end
+      end
+
+      def value(item)
+        if item.block
+          view.capture(&item.block).presence || "—"
+        else
+          item.value
+        end
+      end
+    end
+  end
+end