poetry-core 0.1.11 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc22978b709fc22e859b79edce9929b57a358c7fec1969176f5f3d82e8dacd7a
-  data.tar.gz: 0765f9ded7f711d893f11dba287c2e4014b05a2906e9a3bb3ecf72e3249d7b94
+  metadata.gz: d3a645a256745edb1c315853e3ce88d918362af24218c198a405e66dd2e224f0
+  data.tar.gz: 799ffd218002cdbd8f6ed71745f0a152b559e833c0feb7105fa4afdf3907b689
 SHA512:
-  metadata.gz: 342c1ca9b06f0945c31deb4dab0e25c56e52d2f2afa9ec6dbda9173f1be20e4df699385d070aeb90bbc81a0d43438476c0e3d4a361ca980ea6f4fb163de670cd
-  data.tar.gz: a0a1285525f488233c29823543cb111ea2afc18fc1d2342d3ece955f0770538604367131c82f18792d4a6137bcaa9c1e87e12d7a991d6decd23f1484842393a6
+  metadata.gz: 7bded4405ebe9a3fdb3b09fac843525522cab4ccb163911889421fe65f94427430d4426d1c5b904a38594b5a863edb6a2f66b543cb5a56c8c3bbaf8aee4b09f3
+  data.tar.gz: fb9a1925cacace5469d961f86007fe490da19b8692a69c8061a781885261fb404a705080de32180e8b475064f997953594805b4f08b3251790e88e34b8f7a61b

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.1.13] - 2026-10-13
+
+### Added
+
+- Effect behaviors over the per-connect scope, for controllers of your own and the components ported from other registries: `useInterval` and `useTimeout` (timers cleared at teardown), `useInView` (IntersectionObserver, with `once:`; visible at once where the API is missing), `useMeasure` (ResizeObserver, reporting the size now and on change), `useMutation` (MutationObserver, children in the subtree by default) and `useClipboard` (the Clipboard API with a textarea fallback and a copied state that resets). Import them from `@poetry/controllers/behaviors/<name>`; each is undone by `teardown(this)`.
+- `poetry:design:import` warns when a palette makes border or input too faint to see: in each mode the import touches, both are measured against the background, card and popover, and a pair below 1.15:1 is reported with the nearest visible lightness. The colors still ship, since a faint edge is a design choice and not an accessibility floor. A dark palette that gave border, input and card one value hid every bordered control on cards. The JSON report carries the warnings as `edges`.
+
+## [0.1.12] - 2026-10-07
+
+### Changed
+
+- Version bump with the family; no changes in this gem.
+
 ## [0.1.11] - 2026-10-05
 
 ### Changed

data/app/javascript/poetry/core/behaviors/clipboard.js

@@ -0,0 +1,61 @@
+// useClipboard: copying text for one connect. The async Clipboard API
+// where the page may use it, else a hidden textarea and execCommand; the
+// copied flag resets after `resetAfter` and its timer clears at teardown.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * A copier for the controller's current connect.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {{ resetAfter?: number, onChange?: (copied: boolean) => void }} [options]
+ *   how long the copied state lasts, in milliseconds, and who hears it change
+ * @returns {{ copy: (text: string) => Promise<boolean> }} copy resolves true when the text reached the clipboard
+ */
+export function useClipboard(controller, { resetAfter = 2000, onChange = () => {} } = {}) {
+  const scope = scopeOf(controller)
+  let timer = null
+  scope.defer(() => clearTimeout(timer))
+
+  const copy = async (text) => {
+    const copied = await write(text)
+    if (!copied) return false
+
+    clearTimeout(timer)
+    onChange(true)
+    timer = setTimeout(() => onChange(false), resetAfter)
+    return true
+  }
+
+  return { copy }
+}
+
+const write = async (text) => {
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text)
+      return true
+    }
+  } catch {
+    // Denied or unavailable: fall through to the textarea.
+  }
+
+  return fallback(text)
+}
+
+const fallback = (text) => {
+  const area = document.createElement("textarea")
+  area.value = text
+  area.setAttribute("readonly", "")
+  area.style.position = "fixed"
+  area.style.opacity = "0"
+  document.body.append(area)
+  area.select()
+
+  try {
+    return document.execCommand?.("copy") === true
+  } catch {
+    return false
+  } finally {
+    area.remove()
+  }
+}

data/app/javascript/poetry/core/behaviors/in_view.js

@@ -0,0 +1,36 @@
+// useInView: whether an element is on screen, for one connect, over
+// IntersectionObserver. Reveal-on-scroll and lazy starts read it; the
+// observer disconnects at teardown. Without IntersectionObserver the
+// element counts as visible at once, so content never stays hidden.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Reports `element` entering and leaving the viewport (or `root`) until
+ * teardown(controller). With `once`, it reports the first entry and stops.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {Element} element - the element to watch
+ * @param {(inView: boolean, entry?: IntersectionObserverEntry) => void} onChange - the handler
+ * @param {{ root?: Element, rootMargin?: string, threshold?: number | number[], once?: boolean }} [options]
+ * @returns {() => void} stops watching early; teardown stops it otherwise
+ */
+export function useInView(controller, element, onChange, options = {}) {
+  const { once = false, ...observe } = options
+
+  if (typeof IntersectionObserver === "undefined") {
+    onChange(true)
+    return () => {}
+  }
+
+  let stop = () => {}
+  const observer = new IntersectionObserver((entries) => {
+    for (const entry of entries) {
+      onChange(entry.isIntersecting, entry)
+      if (once && entry.isIntersecting) stop()
+    }
+  }, observe)
+  observer.observe(element)
+  stop = scopeOf(controller).defer(() => observer.disconnect())
+
+  return stop
+}

data/app/javascript/poetry/core/behaviors/interval.js

@@ -0,0 +1,39 @@
+// useInterval and useTimeout: timers that live for one connect. The
+// clears are registered for you, so a ticker or an autoplay never fires
+// into a disconnected controller.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Calls `callback` every `milliseconds` until teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {() => void} callback - the tick
+ * @param {number} milliseconds - the period
+ * @returns {() => void} stops the interval early; teardown stops it otherwise
+ */
+export function useInterval(controller, callback, milliseconds) {
+  const id = setInterval(callback, milliseconds)
+
+  return scopeOf(controller).defer(() => clearInterval(id))
+}
+
+/**
+ * Calls `callback` once after `milliseconds`, unless teardown(controller)
+ * comes first.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {() => void} callback - the delayed call
+ * @param {number} milliseconds - the delay
+ * @returns {() => void} cancels early; teardown cancels otherwise
+ */
+export function useTimeout(controller, callback, milliseconds) {
+  const scope = scopeOf(controller)
+  let cancel = () => {}
+  const id = setTimeout(() => {
+    cancel()
+    callback()
+  }, milliseconds)
+  cancel = scope.defer(() => clearTimeout(id))
+
+  return cancel
+}

data/app/javascript/poetry/core/behaviors/measure.js

@@ -0,0 +1,28 @@
+// useMeasure: an element's size for one connect, over ResizeObserver.
+// The handler runs now with the current size and again on every change;
+// the observer disconnects at teardown. Without ResizeObserver it runs
+// once.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Reports `element`'s content box until teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {Element} element - the element to measure
+ * @param {(size: { width: number, height: number }) => void} onResize - the handler
+ * @returns {() => void} stops measuring early; teardown stops it otherwise
+ */
+export function useMeasure(controller, element, onResize) {
+  const rect = element.getBoundingClientRect()
+  onResize({ width: rect.width, height: rect.height })
+
+  if (typeof ResizeObserver === "undefined") return () => {}
+
+  const observer = new ResizeObserver((entries) => {
+    const box = entries[entries.length - 1]?.contentRect
+    if (box) onResize({ width: box.width, height: box.height })
+  })
+  observer.observe(element)
+
+  return scopeOf(controller).defer(() => observer.disconnect())
+}

data/app/javascript/poetry/core/behaviors/mutation.js

@@ -0,0 +1,20 @@
+// useMutation: changes under an element for one connect, over
+// MutationObserver; the observer disconnects at teardown. The default
+// watches children added and removed anywhere below.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Reports mutations under `element` until teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {Node} element - the node to observe
+ * @param {(records: MutationRecord[]) => void} onMutate - the handler
+ * @param {MutationObserverInit} [options] - what to watch; children in the subtree by default
+ * @returns {() => void} stops observing early; teardown stops it otherwise
+ */
+export function useMutation(controller, element, onMutate, options = { childList: true, subtree: true }) {
+  const observer = new MutationObserver(onMutate)
+  observer.observe(element, options)
+
+  return scopeOf(controller).defer(() => observer.disconnect())
+}

data/lib/poetry/core/design_md/import.rb

@@ -28,6 +28,13 @@ module Poetry
       # @api private
       class Import
         AA = 4.5
+        # The contrast a border or input line needs against the surfaces it
+        # sits on to be seen. Below it every bordered control on that
+        # surface disappears; the import warns and ships anyway, since a
+        # faint edge is a design choice, never an accessibility floor.
+        EDGE = 1.15
+        EDGES = %w[border input].freeze
+        SURFACES = %w[background card popover].freeze
 
         # Conservative cross-ecosystem role aliases - every application is
         # itself reported, so nothing maps silently. Names already matching
@@ -62,12 +69,22 @@ module Poetry
           end
         end
 
+        # One line too faint against a surface it sits on, with the nearest
+        # lightness that clears EDGE.
+        Edge = Struct.new(:mode, :edge, :surface, :ratio, :suggestion, keyword_init: true) do
+          # The warning as one line: mode, the pair, its ratio and the nearest visible value.
+          def to_s
+            line = "[#{mode}] #{edge} on #{surface}: #{format("%.2f", ratio)}:1 (visible needs >= #{EDGE})"
+            suggestion ? "#{line}; nearest visible: #{suggestion}" : line
+          end
+        end
+
         # pins: dark-mode values RESTATED from the shipped defaults for every
         # light-overridden token the source gave no dark value for. Without
         # them a light-only import's :root block would also win in dark mode
         # (:root and .dark tie on specificity; the overrides file loads
         # later) - pinning keeps dark exactly as shipped, no fabrication.
-        Plan = Struct.new(:overrides, :pins, :radius, :applied, :dropped, :contrast, :typography_note,
+        Plan = Struct.new(:overrides, :pins, :radius, :applied, :dropped, :contrast, :edges, :typography_note,
                           keyword_init: true) do
           # Whether the plan changes a radius or any color.
           def any_overrides?
@@ -102,7 +119,7 @@ module Poetry
           end
 
           Plan.new(overrides: overrides, pins: dark_pins(overrides), radius: doc["radius"],
-                   applied: applied, dropped: dropped, contrast: contrast,
+                   applied: applied, dropped: dropped, contrast: contrast, edges: faint_edges(overrides),
                    typography_note: typography_note(doc))
         end
 
@@ -114,10 +131,19 @@ module Poetry
         # @param candidate [Tokens::Color] the color to walk
         # @param against [Tokens::Color] the fixed other member of the pair
         # @return [Tokens::Color, nil] the nearest passing color, or nil
-        def nearest_aa(candidate, against)
+        def nearest_aa(candidate, against) = nearest_contrast(candidate, against, AA)
+
+        # The same walk to any contrast floor: AA for text, EDGE for lines.
+        #
+        # @param candidate [Tokens::Color] the color to walk
+        # @param against [Tokens::Color] the fixed other member of the pair
+        # @param floor [Float] the ratio the pair must reach
+        # @return [Tokens::Color, nil] the nearest passing color, or nil
+        def nearest_contrast(candidate, against, floor)
           step = candidate.l > against.l ? 0.01 : -0.01
+          step = 0.01 if candidate.l == against.l && against.l < 0.5
           color = candidate
-          until color.contrast_ratio(against) >= AA
+          until color.contrast_ratio(against) >= floor
             next_l = (color.l + step).round(3)
             return nil unless next_l.between?(0.0, 1.0)
 
@@ -166,6 +192,28 @@ module Poetry
           end
         end
 
+        # Border and input against every surface, in each mode the import
+        # touches one of them: the lines too faint to see (the case of a dark
+        # palette giving border, input and card one value).
+        def faint_edges(overrides)
+          overrides.flat_map do |mode, colors|
+            next [] unless colors.keys.intersect?(EDGES + SURFACES)
+
+            EDGES.product(SURFACES).filter_map do |edge, surface|
+              line = merged(mode, edge, overrides)
+              fill = merged(mode, surface, overrides)
+              next unless line && fill
+
+              ratio = line.contrast_ratio(fill)
+              next if ratio >= EDGE
+
+              walked = nearest_contrast(line, fill, EDGE)
+              Edge.new(mode: mode, edge: edge, surface: surface, ratio: ratio,
+                       suggestion: walked && "--#{edge}: #{walked.css}")
+            end
+          end
+        end
+
         # Every ledger pair an override touches, measured on the merged set.
         def enforce_contrast(overrides, force:)
           Tokens::ContrastGate::LEDGER.flat_map do |mode, specs|

data/lib/poetry/core/version.rb

@@ -4,6 +4,6 @@ module Poetry
   module Core
     # The gem version. Every gem in the family carries the same version
     # and pins poetry-core to it exactly.
-    VERSION = "0.1.11"
+    VERSION = "0.1.13"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: poetry-core
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.1.13
 platform: ruby
 authors:
 - Matt Solt
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -101,10 +101,15 @@ files:
 - app/javascript/poetry/core/autocomplete_controller.js
 - app/javascript/poetry/core/behaviors/announce.js
 - app/javascript/poetry/core/behaviors/before_cache.js
+- app/javascript/poetry/core/behaviors/clipboard.js
 - app/javascript/poetry/core/behaviors/escape.js
+- app/javascript/poetry/core/behaviors/in_view.js
+- app/javascript/poetry/core/behaviors/interval.js
 - app/javascript/poetry/core/behaviors/layers.js
 - app/javascript/poetry/core/behaviors/listen.js
+- app/javascript/poetry/core/behaviors/measure.js
 - app/javascript/poetry/core/behaviors/mobile.js
+- app/javascript/poetry/core/behaviors/mutation.js
 - app/javascript/poetry/core/behaviors/overlay.js
 - app/javascript/poetry/core/behaviors/portal.js
 - app/javascript/poetry/core/behaviors/presence.js