lightning_ui_kit 0.4.0 → 0.4.1

data/app/components/lightning_ui_kit/chart_component.html.erb

@@ -8,7 +8,7 @@
       <div class="lui:mb-3 lui:flex lui:flex-wrap lui:items-center lui:gap-4">
         <% series.each do |s| %>
           <div class="lui:flex lui:items-center lui:gap-1.5 lui:text-xs lui:text-foreground-muted">
-            <span class="lui:size-2.5 lui:rounded-sm" style="background-color: <%= s[:color] %>;"></span>
+            <span class="lui:size-2 lui:shrink-0 lui:rounded-[2px]" style="background-color: <%= s[:color] %>;"></span>
             <%= s[:label] %>
           </div>
         <% end %>
@@ -20,8 +20,8 @@
         <defs>
           <% series.each_with_index do |s, i| %>
             <linearGradient id="<%= gradient_id(i) %>" x1="0" y1="0" x2="0" y2="1">
-              <stop offset="0%" stop-color="<%= s[:color] %>" stop-opacity="0.35" />
-              <stop offset="100%" stop-color="<%= s[:color] %>" stop-opacity="0.02" />
+              <stop offset="5%" stop-color="<%= s[:color] %>" stop-opacity="0.8" />
+              <stop offset="95%" stop-color="<%= s[:color] %>" stop-opacity="0.1" />
             </linearGradient>
           <% end %>
         </defs>
@@ -37,26 +37,46 @@
         <% y_ticks.each do |tick| %>
           <text x="<%= plot_left - 8 %>" y="<%= (tick[:y] + 4).round(2) %>" text-anchor="end" font-size="11" fill="var(--lui-theme-foreground-muted)"><%= tick[:label] %></text>
         <% end %>
-        <% x_positions.each do |pos| %>
+        <% x_axis_labels.each do |pos| %>
           <text x="<%= pos[:x].round(2) %>" y="<%= view_height - 8 %>" text-anchor="middle" font-size="11" fill="var(--lui-theme-foreground-muted)"><%= pos[:label] %></text>
         <% end %>
       <% end %>
 
+      <g data-lui-chart-target="cursor" style="display: none">
+        <% if bar? %>
+          <rect data-role="cursor-band" x="0" y="<%= plot_top %>" width="0" height="<%= (plot_bottom - plot_top).round(2) %>" fill="var(--lui-theme-surface-hover)" />
+        <% else %>
+          <line data-role="cursor-line" x1="0" x2="0" y1="<%= plot_top %>" y2="<%= plot_bottom %>" stroke="var(--lui-theme-border-hover)" stroke-width="1" stroke-dasharray="3 3" />
+        <% end %>
+      </g>
+
       <% if bar? %>
         <% bars.each do |bar| %>
           <path d="<%= bar_path(bar) %>" fill="<%= bar[:color] %>" data-role="bar" />
         <% end %>
       <% else %>
         <% series.each_with_index do |s, i| %>
-          <% points = line_points(s) %>
+          <% segments = line_segments(s) %>
+          <% strokes = segments.select { |points| points.size > 1 } %>
           <% if area? %>
-            <path d="<%= area_path(points) %>" fill="url(#<%= gradient_id(i) %>)" data-role="area" />
+            <% strokes.each do |points| %>
+              <path d="<%= area_path(points) %>" fill="url(#<%= gradient_id(i) %>)" fill-opacity="0.4" data-role="area" />
+            <% end %>
+          <% end %>
+          <% strokes.each do |points| %>
+            <path d="<%= line_path(points) %>" fill="none" stroke="<%= s[:color] %>" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" data-role="line" />
           <% end %>
-          <polyline points="<%= polyline(points) %>" fill="none" stroke="<%= s[:color] %>" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" data-role="line" />
-          <% points.each do |x, y| %>
+          <% dots = show_dots? ? segments : segments.select { |points| points.size == 1 } %>
+          <% dots.flatten(1).each do |x, y| %>
             <circle cx="<%= x.round(2) %>" cy="<%= y.round(2) %>" r="3" fill="var(--lui-theme-surface)" stroke="<%= s[:color] %>" stroke-width="2" data-role="point" />
           <% end %>
         <% end %>
+
+        <g data-lui-chart-target="markers" style="display: none">
+          <% series.each do |s| %>
+            <circle data-role="active-dot" cx="0" cy="0" r="4" fill="<%= s[:color] %>" stroke="var(--lui-theme-surface)" stroke-width="2" />
+          <% end %>
+        </g>
       <% end %>
 
       <% hover_columns.each do |col| %>
@@ -70,11 +90,13 @@
           data-role="column"
           data-label="<%= col[:label] %>"
           data-payload="<%= col[:payload] %>"
+          data-cursor-x="<%= col[:cursor_x].round(2) %>"
+          data-markers="<%= col[:markers] %>"
           data-action="mouseenter->lui-chart#show mousemove->lui-chart#move mouseleave->lui-chart#hide"
         />
       <% end %>
     </svg>
 
-    <div data-lui-chart-target="tooltip" class="lui:hidden lui:pointer-events-none lui:absolute lui:z-50 lui:flex lui:min-w-[8rem] lui:flex-col lui:gap-1 lui:rounded-lg lui:border lui:border-border lui:bg-surface lui:px-2.5 lui:py-1.5 lui:text-xs lui:shadow-md"></div>
+    <div data-lui-chart-target="tooltip" class="lui:hidden lui:pointer-events-none lui:absolute lui:z-50 lui:grid lui:min-w-[8rem] lui:items-start lui:gap-1.5 lui:rounded-lg lui:border lui:border-border lui:bg-surface lui:px-2.5 lui:py-1.5 lui:text-xs lui:shadow-xl"></div>
   <% end %>
 <% end %>

data/app/components/lightning_ui_kit/chart_component.rb

@@ -1,12 +1,31 @@
 class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
   TYPES = %i[bar line area].freeze
+  UNITS = %i[decimal percent bytes count duration_ms].freeze
+  CURVES = %i[monotone linear].freeze
 
   VIEW_WIDTH = 640
   PAD_RIGHT = 16
   PAD_TOP = 12
   AXIS_PAD_LEFT = 44
 
-  def initialize(data:, type: :bar, series: nil, x_key: :label, height: 260, show_grid: true, show_legend: true, show_axis: true, **options)
+  DEFAULT_MAX_X_LABELS = 8
+  Y_TICK_STEPS = 4
+  # Above this many points a dot per value reads as a bead string, so dots:
+  # :auto drops them and relies on the hover marker instead.
+  AUTO_DOT_LIMIT = 12
+  BAR_RADIUS = 4.0
+  # Share of the category band the bars occupy, and of each slot a bar fills.
+  BAR_BAND = 0.8
+  BAR_FILL = 0.9
+  # Rendered in place of a value for missing (nil) data points.
+  NIL_LABEL = "–".freeze
+  BYTE_UNITS = %w[B KiB MiB GiB TiB PiB EiB].freeze
+  DECIMAL_MULTIPLIERS = [1, 2, 5, 10].freeze
+  BINARY_MULTIPLIERS = [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024].freeze
+
+  def initialize(data:, type: :bar, series: nil, x_key: :label, height: 260, show_grid: true, show_legend: true, show_axis: true,
+    unit: :decimal, y_format: nil, max_x_labels: DEFAULT_MAX_X_LABELS, y_min: nil, y_max: nil, span_gaps: false,
+    curve: :monotone, dots: :auto, **options)
     @data = Array(data).map { |row| row.respond_to?(:to_h) ? row.to_h.symbolize_keys : row }
     @type = TYPES.include?(type) ? type : :bar
     @x_key = x_key.to_sym
@@ -14,6 +33,14 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
     @show_grid = show_grid
     @show_legend = show_legend
     @show_axis = show_axis
+    @unit = UNITS.include?(unit&.to_sym) ? unit.to_sym : :decimal
+    @y_format = y_format
+    @max_x_labels = max_x_labels
+    @y_min = y_min
+    @y_max = y_max
+    @span_gaps = span_gaps
+    @curve = (curve&.to_sym == :linear) ? :linear : :monotone
+    @dots = dots
     @series = build_series(series)
     @options = options
   end
@@ -44,6 +71,20 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
     @show_legend && @series.any?
   end
 
+  def span_gaps?
+    @span_gaps
+  end
+
+  def smooth?
+    @curve == :monotone
+  end
+
+  # shadcn draws line/area series without per-point dots; :auto keeps them only
+  # while the series is sparse enough for them to read as markers.
+  def show_dots?
+    (@dots == :auto) ? count <= AUTO_DOT_LIMIT : !!@dots
+  end
+
   def classes
     merge_classes([
       "lui:relative lui:w-full lui:text-foreground",
@@ -89,12 +130,37 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
 
   def x_label(row) = row[@x_key]
 
-  def value_for(row, series) = row[series[:key]].to_f
+  # nil for a missing data point so lines can break and bars can be skipped.
+  # Anything unparseable ("n/a", "-", "") counts as missing rather than zero.
+  def value_for(row, series)
+    raw = row[series[:key]]
+    return nil if raw.nil?
+    return raw.to_f if raw.is_a?(Numeric)
+
+    Float(raw.to_s.strip, exception: false)
+  end
+
+  # --- y domain ---
+
+  def domain_min
+    @domain_min ||= (@y_min || default_domain_min).to_f
+  end
+
+  def domain_max
+    @domain_max ||= begin
+      top = @y_max ? @y_max.to_f : nice_domain_max
+      (top > domain_min) ? top : domain_min + 1.0
+    end
+  end
 
   def y_for(value)
-    return plot_bottom if chart_max.zero?
+    return plot_bottom if value.nil?
+
+    span = domain_max - domain_min
+    return plot_bottom if span <= 0
 
-    plot_bottom - (value.to_f / chart_max) * plot_height
+    ratio = ((value.to_f - domain_min) / span).clamp(0.0, 1.0)
+    plot_bottom - ratio * plot_height
   end
 
   def point_x(index)
@@ -103,10 +169,12 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
     plot_left + (index.to_f / (count - 1)) * plot_width
   end
 
-  def y_ticks(steps = 4)
+  def y_ticks(steps = Y_TICK_STEPS)
+    span = domain_max - domain_min
+
     (0..steps).map do |i|
-      value = chart_max * i / steps
-      {label: format_number(value), y: y_for(value)}
+      value = domain_min + span * i / steps
+      {label: format_value(value), y: y_for(value)}
     end
   end
 
@@ -117,26 +185,44 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
     end
   end
 
+  # Evenly spaced subset of x_positions (first and last always kept) so dense
+  # series don't render overlapping axis text. Data points are unaffected.
+  def x_axis_labels
+    positions = x_positions
+    label_indices(positions.size).map { |i| positions[i] }
+  end
+
+  # Bars are measured from zero (or the nearest edge of the domain when zero
+  # falls outside it), so a negative value hangs below the baseline instead of
+  # growing upward from the domain floor.
+  def bar_baseline = 0.0.clamp(domain_min, domain_max)
+
   def bars
     group_width = bar_group_width
-    inner = group_width * 0.2
-    band = group_width - inner
-    bar_width = @series.empty? ? band : band / @series.size
+    slot = bar_slot_width
+    width = slot * BAR_FILL
+    # Bars are centred in their category band so they line up with the tick
+    # label, the hover cursor and the grid.
+    cluster = (@series.size - 1) * slot + width
+    base_y = y_for(bar_baseline)
 
     @data.each_with_index.flat_map do |row, i|
-      group_x = plot_left + i * group_width + inner / 2.0
-      @series.each_with_index.map do |s, si|
+      group_x = plot_left + i * group_width + (group_width - cluster) / 2.0
+      @series.each_with_index.filter_map do |s, si|
         value = value_for(row, s)
+        next if value.nil?
+
         y = y_for(value)
         {
-          x: group_x + si * bar_width,
-          y: y,
-          width: bar_width * 0.9,
-          height: [plot_bottom - y, 0].max,
+          x: group_x + si * slot,
+          y: [y, base_y].min,
+          width: width,
+          height: (y - base_y).abs,
+          negative: y > base_y,
           color: s[:color],
           label: x_label(row),
           series_label: s[:label],
-          value: format_number(value)
+          value: format_value(value)
         }
       end
     end
@@ -144,46 +230,71 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
 
   def line_points(series)
     @data.each_with_index.map do |row, i|
-      [point_x(i), y_for(value_for(row, series))]
+      value = value_for(row, series)
+      value.nil? ? nil : [point_x(i), y_for(value)]
     end
   end
 
-  def polyline(points)
-    points.map { |x, y| "#{x.round(2)},#{y.round(2)}" }.join(" ")
+  # Contiguous runs of plottable points. A nil value ends the current run so the
+  # line shows a gap, unless span_gaps: was requested.
+  def line_segments(series)
+    points = line_points(series)
+    return [points.compact].reject(&:empty?) if span_gaps?
+
+    points.chunk_while { |a, b| !a.nil? && !b.nil? }
+      .map(&:compact)
+      .reject(&:empty?)
+  end
+
+  # Stroke path for one contiguous run of points.
+  def line_path(points)
+    return "" if points.empty?
+
+    "M #{r2(points.first[0])} #{r2(points.first[1])} #{curve_commands(points)}".strip
   end
 
+  # The stroke path closed down to the baseline on both ends.
   def area_path(points)
     return "" if points.empty?
 
-    segments = ["M #{points.first[0].round(2)} #{plot_bottom.round(2)}"]
-    points.each { |x, y| segments << "L #{x.round(2)} #{y.round(2)}" }
-    segments << "L #{points.last[0].round(2)} #{plot_bottom.round(2)} Z"
-    segments.join(" ")
+    first = points.first
+    last = points.last
+    [
+      "M #{r2(first[0])} #{r2(plot_bottom)}",
+      "L #{r2(first[0])} #{r2(first[1])}",
+      curve_commands(points),
+      "L #{r2(last[0])} #{r2(plot_bottom)}",
+      "Z"
+    ].reject(&:empty?).join(" ")
   end
 
-  # Path for a bar with rounded top corners and a square base.
+  # Path for a bar with a square base at the baseline and rounded corners on the
+  # free end - the top for positive values, the bottom for negative ones.
   def bar_path(bar)
     x = bar[:x]
-    y = bar[:y]
     w = bar[:width]
     h = bar[:height]
     return "" if h <= 0 || w <= 0
 
-    r = [6.0, w / 2.0, h].min
+    r = [BAR_RADIUS, w / 2.0, h].min
     x2 = x + w
-    bottom = y + h
+    base = bar[:negative] ? bar[:y] : bar[:y] + h
+    tip = bar[:negative] ? bar[:y] + h : bar[:y]
+    # Signed step from the tip back toward the baseline.
+    inset = bar[:negative] ? -r : r
     [
-      "M #{r2(x)} #{r2(bottom)}",
-      "L #{r2(x)} #{r2(y + r)}",
-      "Q #{r2(x)} #{r2(y)} #{r2(x + r)} #{r2(y)}",
-      "L #{r2(x2 - r)} #{r2(y)}",
-      "Q #{r2(x2)} #{r2(y)} #{r2(x2)} #{r2(y + r)}",
-      "L #{r2(x2)} #{r2(bottom)}",
+      "M #{r2(x)} #{r2(base)}",
+      "L #{r2(x)} #{r2(tip + inset)}",
+      "Q #{r2(x)} #{r2(tip)} #{r2(x + r)} #{r2(tip)}",
+      "L #{r2(x2 - r)} #{r2(tip)}",
+      "Q #{r2(x2)} #{r2(tip)} #{r2(x2)} #{r2(tip + inset)}",
+      "L #{r2(x2)} #{r2(base)}",
       "Z"
     ].join(" ")
   end
 
-  # Invisible full-height bands (one per category) that drive the hover tooltip.
+  # Invisible full-height bands (one per category) that drive the hover tooltip,
+  # cursor and active dots.
   def hover_columns
     step = (count > 1) ? plot_width.to_f / (count - 1) : plot_width.to_f
 
@@ -197,29 +308,145 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
       end
       left = [x, plot_left].max
       right = [x + w, plot_right].min
-      {x: left, width: [right - left, 0].max, label: x_label(row), payload: payload_for(i)}
+      {
+        x: left,
+        width: [right - left, 0].max,
+        cursor_x: bar? ? plot_left + i * bar_group_width + bar_group_width / 2.0 : point_x(i),
+        markers: markers_for(i),
+        label: x_label(row),
+        payload: payload_for(i)
+      }
     end
   end
 
+  # Y position of each series at the given index, or null where the value is
+  # missing, so the controller can place one active dot per series on hover.
+  def markers_for(index)
+    row = @data[index]
+    @series.map do |s|
+      value = value_for(row, s)
+      value.nil? ? nil : r2(y_for(value))
+    end.to_json
+  end
+
   def payload_for(index)
     row = @data[index]
     @series.map do |s|
-      {label: s[:label], value: format_number(value_for(row, s)), color: s[:color]}
+      {label: s[:label], value: format_value(value_for(row, s)), color: s[:color]}
     end.to_json
   end
 
+  # Applies y_format: when given, otherwise the unit: preset. Shared by axis
+  # ticks and tooltip payloads so the two always agree.
+  def format_value(value)
+    return NIL_LABEL if value.nil?
+    return @y_format.call(value).to_s if @y_format.respond_to?(:call)
+
+    case @unit
+    when :percent then format_percent(value.to_f)
+    when :bytes then format_bytes(value.to_f)
+    when :count then format_count(value.to_f)
+    when :duration_ms then format_duration_ms(value.to_f)
+    else format_decimal(value.to_f)
+    end
+  end
+
   private
 
   def r2(number)
     number.round(2)
   end
 
-  def chart_max
-    @chart_max ||= begin
-      values = @data.flat_map { |row| @series.map { |s| value_for(row, s) } }
-      max = values.max || 0
-      (max <= 0) ? 1.0 : max.to_f
+  # Segment commands after the opening `M`, honouring the curve: option.
+  def curve_commands(points)
+    return "" if points.size < 2
+    return points.drop(1).map { |x, y| "L #{r2(x)} #{r2(y)}" }.join(" ") unless smooth?
+
+    tangents = monotone_tangents(points)
+    points.each_cons(2).each_with_index.map do |(from, to), i|
+      dx = (to[0] - from[0]) / 3.0
+      c1 = [from[0] + dx, from[1] + tangents[i] * dx]
+      c2 = [to[0] - dx, to[1] - tangents[i + 1] * dx]
+      "C #{r2(c1[0])} #{r2(c1[1])} #{r2(c2[0])} #{r2(c2[1])} #{r2(to[0])} #{r2(to[1])}"
+    end.join(" ")
+  end
+
+  # Fritsch-Carlson slopes: a monotone cubic that never overshoots the data,
+  # matching the "monotone"/"natural" curve shadcn uses for lines and areas.
+  def monotone_tangents(points)
+    slopes = points.each_cons(2).map do |(x1, y1), (x2, y2)|
+      dx = x2 - x1
+      dx.zero? ? 0.0 : (y2 - y1) / dx
     end
+
+    tangents = [slopes.first]
+    slopes.each_cons(2) do |left, right|
+      tangents << ((left * right <= 0) ? 0.0 : (left + right) / 2.0)
+    end
+    tangents << slopes.last
+
+    slopes.each_with_index do |slope, i|
+      if slope.zero?
+        tangents[i] = 0.0
+        tangents[i + 1] = 0.0
+        next
+      end
+
+      a = tangents[i] / slope
+      b = tangents[i + 1] / slope
+      magnitude = a * a + b * b
+      next if magnitude <= 9
+
+      scale = 3.0 * slope / Math.sqrt(magnitude)
+      tangents[i] = scale * a
+      tangents[i + 1] = scale * b
+    end
+
+    tangents
+  end
+
+  def data_values
+    @data_values ||= @data.flat_map { |row| @series.map { |s| value_for(row, s) } }.compact
+  end
+
+  def default_domain_min
+    min = data_values.min
+    (min && min < 0) ? -nice_step(min.abs) : 0.0
+  end
+
+  # Round the data max up so that the axis lands on 1/2/5 × 10ⁿ values.
+  def nice_domain_max(steps = Y_TICK_STEPS)
+    max = data_values.max
+    span = max ? max - domain_min : 0
+    return domain_min + 1.0 if span <= 0
+
+    domain_min + nice_step(span / steps) * steps
+  end
+
+  # Smallest "round" value >= the given magnitude: 1/2/5 × 10ⁿ normally, or
+  # 1/2/4/…/1024 × 1024ⁿ for :bytes so ticks land on whole KiB/MiB/GiB.
+  def nice_step(value)
+    return 1.0 if value <= 0
+
+    radix, multipliers = (@unit == :bytes) ? [1024, BINARY_MULTIPLIERS] : [10, DECIMAL_MULTIPLIERS]
+    exponent = Math.log(value, radix).floor
+    base = radix.to_f**exponent
+    fraction = value / base
+
+    step = (multipliers.find { |m| fraction <= m } || multipliers.last) * base
+    # :count renders whole numbers, so a sub-integer step would repeat labels.
+    (@unit == :count) ? [step, 1.0].max : step
+  end
+
+  def label_indices(total)
+    return (0...total).to_a unless @max_x_labels
+
+    limit = @max_x_labels.to_i
+    return (0...total).to_a if limit <= 0 || total <= limit
+    return [0] if limit == 1
+
+    step = (total - 1) / (limit - 1).to_f
+    (0...limit).map { |i| (i * step).round }.uniq
   end
 
   def bar_group_width
@@ -228,6 +455,12 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
     plot_width.to_f / count
   end
 
+  # Horizontal room for one series within a category band.
+  def bar_slot_width
+    band = bar_group_width * BAR_BAND
+    @series.empty? ? band : band / @series.size
+  end
+
   def build_series(series)
     definitions =
       if series
@@ -250,14 +483,52 @@ class LightningUiKit::ChartComponent < LightningUiKit::BaseComponent
     return [] if @data.empty?
 
     candidates = @data.first.keys - [@x_key]
-    numeric = candidates.select { |key| @data.all? { |row| row[key].is_a?(Numeric) } }
+    numeric = candidates.select { |key| @data.all? { |row| row[key].is_a?(Numeric) || row[key].nil? } }
     return numeric unless numeric.empty?
 
     @data.first.key?(:value) ? [:value] : []
   end
 
-  def format_number(value)
-    rounded = value.to_f.round(2)
-    (rounded % 1).zero? ? rounded.to_i.to_s : rounded.to_s
+  def trim(number)
+    (number % 1).zero? ? number.to_i.to_s : number.to_s
+  end
+
+  def format_decimal(value)
+    trim(value.round(2))
+  end
+
+  def format_percent(value)
+    # Sub-1% values need a second decimal or neighbouring ticks collapse.
+    decimals = (!value.zero? && value.abs < 1) ? 2 : 1
+    "#{trim(value.round(decimals))}%"
+  end
+
+  def format_bytes(value)
+    return "0 B" if value.zero?
+
+    sign = value.negative? ? "-" : ""
+    magnitude = value.abs
+    exponent = Math.log(magnitude, 1024).floor.clamp(0, BYTE_UNITS.size - 1)
+    scaled = magnitude / (1024.0**exponent)
+
+    "#{sign}#{trim(scaled.round(exponent.zero? ? 0 : 2))} #{BYTE_UNITS[exponent]}"
+  end
+
+  def format_count(value)
+    ActiveSupport::NumberHelper.number_to_delimited(value.round)
+  end
+
+  def format_duration_ms(value)
+    magnitude = value.abs
+
+    if magnitude < 1
+      "#{trim(value.round(2))} ms"
+    elsif magnitude < 1_000
+      "#{trim(value.round((magnitude < 10) ? 1 : 0))} ms"
+    elsif magnitude < 60_000
+      "#{trim((value / 1_000.0).round(2))} s"
+    else
+      "#{trim((value / 60_000.0).round(2))} min"
+    end
   end
 end

data/app/components/lightning_ui_kit/description_list/item_component.html.erb

@@ -1,13 +1,3 @@
-<dt class="lui:col-start-1 lui:border-t lui:border-border-subtle lui:pt-3 lui:text-foreground-muted lui:first:border-none lui:sm:border-t lui:sm:border-border-subtle lui:sm:py-3 lui:flex lui:items-center">
-  <%= @label %>
-</dt>
+<%= tag.dt(@label, class: label_classes) %>
 
-<dd class="lui:pt-1 lui:pb-3 lui:text-foreground lui:sm:border-t lui:sm:border-border-subtle lui:sm:py-3 lui:sm:nth-2:border-none lui:flex lui:items-center">
-  <div class="lui:w-full">
-    <% if @value %>
-      <%= @value %>
-    <% else %>
-      <%= content %>
-    <% end %>
-  </div>
-</dd>
+<%= tag.dd(value, class: value_classes, data: data) %>

data/app/components/lightning_ui_kit/description_list/item_component.rb

@@ -1,7 +1,34 @@
 class LightningUiKit::DescriptionList::ItemComponent < LightningUiKit::BaseComponent
-  def initialize(label:, value: nil, **options)
+  LABEL_CLASSES = "lui:col-start-1 lui:min-w-0 lui:break-words lui:border-t lui:border-border-subtle lui:pt-3 lui:text-foreground-muted lui:first:border-none lui:sm:border-t lui:sm:border-border-subtle lui:sm:py-3"
+  VALUE_CLASSES = "lui:min-w-0 lui:break-words lui:pt-1 lui:pb-3 lui:text-foreground lui:sm:border-t lui:sm:border-border-subtle lui:sm:py-3 lui:sm:first-of-type:border-none"
+
+  def initialize(label:, value: nil, body: nil, **options)
     @label = label
     @value = value
+    @body = body
     @options = options
   end
+
+  def label_classes
+    merge_classes([LABEL_CLASSES, @options[:label_class]].compact.join(" "))
+  end
+
+  def value_classes
+    merge_classes([VALUE_CLASSES, @options[:class]].compact.join(" "))
+  end
+
+  def data
+    @options[:data] || {}
+  end
+
+  def value
+    return @value unless @value.nil?
+    return content if @body.nil?
+
+    # Blocks that build markup write to the output buffer; blocks that just
+    # return a value (an Integer, a Date, ...) leave it empty — keep both.
+    returned = nil
+    buffer = view_context.with_output_buffer { returned = @body.call }
+    buffer.presence || returned
+  end
 end

data/app/components/lightning_ui_kit/description_list_component.html.erb

@@ -1,5 +1,5 @@
-<dl class="lui:grid lui:grid-cols-1 lui:text-base/6 lui:sm:grid-cols-[min(50%,--spacing(80))_auto] lui:sm:text-sm/6">
+<%= tag.dl(class: classes, data: data) do %>
   <% items.each do |item| %>
     <%= item %>
   <% end %>
-</dl>
+<% end %>

data/app/components/lightning_ui_kit/description_list_component.rb

@@ -1,3 +1,29 @@
 class LightningUiKit::DescriptionListComponent < LightningUiKit::BaseComponent
-  renders_many :items, LightningUiKit::DescriptionList::ItemComponent
+  renders_many :items, ->(label:, value: nil, body: nil, **options) do
+    LightningUiKit::DescriptionList::ItemComponent.new(label: label, value: value, body: body, **options)
+  end
+
+  # ViewComponent funnels slot blocks through Rails' `capture`, which discards
+  # non-String return values (Integers, Dates, ...), rendering blank values.
+  # Route the block around that wrapper via the body: argument so the item can
+  # evaluate it instead.
+  alias_method :__with_item_slot, :with_item
+  def with_item(label:, value: nil, **options, &block)
+    __with_item_slot(label: label, value: value, body: block, **options)
+  end
+
+  def initialize(**options)
+    @options = options
+  end
+
+  def classes
+    merge_classes([
+      "lui:grid lui:grid-cols-1 lui:text-base/6 lui:sm:grid-cols-[min(50%,--spacing(80))_minmax(0,auto)] lui:sm:text-sm/6",
+      @options[:class]
+    ].compact.join(" "))
+  end
+
+  def data
+    @options[:data] || {}
+  end
 end