studio-engine 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4e53e209d300c3d55aa211ae40024421ee78734929e1e1db1fd683fa84ffeb0
-  data.tar.gz: 372749c4b18ba3072cd4977ee5e2481d18b870ba14b93e44cca9863f5781c1f6
+  metadata.gz: 31ed2941026e5bf0114872ba16dd7a9b94b1a472d5407ff82ec604ba2e659962
+  data.tar.gz: 1fda4b1328315323b8afcee644a68acc8678e756762a88b289ea10e0fc46a6cf
 SHA512:
-  metadata.gz: b984b2a14f1065b8c021a87a28ea50f447870361a43b027bb26538d7c360eb5a89c75f3aa8241b0889578af54325421727b6967f8c2a3ec6e3daaf64c36c5295
-  data.tar.gz: bee489407d99c8c5b6d7beda43161b01de9e06014453eb9b80a890b9c913563c2520059c36c18b67d1aaa2dbaddbf933a047878fd4d7abffb90514d8a4ef744d
+  metadata.gz: 6431e1dafbd0a614e1c0a6abe25004ab3888a3d1e7c263ab97d7883e10bcedde60da03f16c98b262d9926173749343b00c33d6a5580db9fc299c8b1b355a9665
+  data.tar.gz: 7513d2735c2535ed520530eab4adc0b1ce60de617488e4fa934e43beb31ef330e7e49c8837e3310aa92467559dbabf714fab43b81d86a0d52cebce8f85674e35

data/CHANGELOG.md

@@ -4,6 +4,24 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.9.0 — 2026-06-23
+
+### Added
+- **`Studio::Enumeral`** — a shared, DB-backed enumeration table for the whole
+  ecosystem. Every "list of fixed, labeled, colored values" (Pokémon types first;
+  statuses/tiers/roles later) is rows in ONE `studio_enumerals` table, grouped by
+  `category`: a stable machine `key`, a human `label`, a `color` hex, a display
+  `position`, a sparse `rank` (gappy 100/200/… domain ranking — e.g. most-common
+  first — distinct from display order), and `metadata` (jsonb) for
+  category-specific extras. Class helpers `catalog`, `lookup`, `color_map` (one
+  query → `{ key => color }`), `color_for(category, key, fallback:)`, and a
+  metadata-backed `emoji` reader + `emoji_map` (decorative glyphs live in
+  `metadata`, not a column); scopes `ordered` / `by_rank`; `available?` degrades
+  to empty when the table isn't installed. Shipped by the gem like `Studio::Link` /
+  `Studio::EmailDelivery` — reference migration `create_studio_enumerals`
+  installed per app (copy into `db/migrate`). No behavior is attached: a consumer
+  adopts a new category by seeding rows, no code change.
+
 ## 0.8.0 — 2026-06-21
 
 ### Added

data/app/models/studio/enumeral.rb

@@ -0,0 +1,85 @@
+module Studio
+  # A shared, DB-backed enumeration table for the whole ecosystem. Every "list of
+  # fixed, labeled, colored values" — Pokémon types (its first use), and later
+  # statuses, tiers, roles, … — is just rows in ONE studio_enumerals table,
+  # grouped by `category`. Each row is identity + presentation: a stable machine
+  # `key` ("fire"), a human `label` ("Fire"), a `color` hex ("#EE8130"), and a
+  # `position` for ordering within its category. `metadata` (jsonb) carries any
+  # category-specific extras off the columns.
+  #
+  # Shipped by the gem like Studio::Link / Studio::EmailDelivery: the model lives
+  # here, the table lives in each consumer app (copy the reference migration into
+  # db/migrate). No behavior is attached — it is pure reference data the apps
+  # read, so a consumer adopts a new category by seeding rows, no code change.
+  class Enumeral < ApplicationRecord
+    self.table_name = "studio_enumerals"
+
+    HEX = /\A#(?:\h{3}|\h{6})\z/
+
+    validates :category, presence: true
+    validates :key, presence: true,
+                    uniqueness: { scope: :category, case_sensitive: false }
+    validates :color, format: { with: HEX, message: "must be a hex color like #EE8130" },
+                      allow_blank: true
+
+    scope :in_category, ->(category) { where(category: category.to_s) }
+    scope :ordered,     -> { order(:position, :key) }
+    # By `rank` (a sparse 100/200/… domain ranking), nulls last — for categories
+    # ordered by something other than display position, e.g. most-common-first.
+    scope :by_rank,     -> { order(:rank) }
+
+    class << self
+      # True only when the table is actually migrated in this app's DB, so a
+      # consumer that hasn't installed the migration degrades to "empty" instead
+      # of crashing (mirrors Studio::EmailDelivery.available?).
+      def available?
+        connection.data_source_exists?(table_name)
+      rescue ActiveRecord::ActiveRecordError, NoMethodError
+        false
+      end
+
+      # The ordered list of a category's enumerals — the relation a view iterates
+      # (one query). Returns an empty relation when the table isn't installed yet,
+      # so callers can `.each` safely pre-migration.
+      def catalog(category)
+        return none unless available?
+
+        in_category(category).ordered
+      end
+
+      # The single enumeral for (category, key), or nil.
+      def lookup(category, key)
+        return nil unless available?
+
+        in_category(category).find_by(key: key.to_s)
+      end
+
+      # { key => color } for a category in ONE query — the shape a view wants:
+      # build it once, then look up each cell with no extra queries (avoids an
+      # N+1 when rendering many rows, e.g. the /pokemon type badges).
+      def color_map(category)
+        catalog(category).pluck(:key, :color).to_h
+      end
+
+      # Just the color for a single (category, key), with an optional fallback
+      # when the key is unknown or the table isn't installed yet.
+      def color_for(category, key, fallback: nil)
+        return fallback unless available?
+
+        in_category(category).where(key: key.to_s).limit(1).pick(:color) || fallback
+      end
+
+      # { key => emoji } for a category in ONE query — the metadata sibling of
+      # color_map, for decorative glyphs kept in `metadata` rather than a column.
+      def emoji_map(category)
+        catalog(category).pluck(:key, :metadata).to_h { |key, meta| [key, meta && meta["emoji"]] }
+      end
+    end
+
+    # A decorative glyph for the value, kept in `metadata` (not a column) since
+    # it's a presentation extra — e.g. a Pokémon type's emoji. Nil when unset.
+    def emoji
+      metadata && metadata["emoji"]
+    end
+  end
+end

data/db/migrate/20260623130000_create_studio_enumerals.rb

@@ -0,0 +1,30 @@
+# Reference migration for the Studio::Enumeral model. Like the engine's
+# studio_links / studio_email_deliveries migrations, each consumer app installs
+# its own copy of this into db/migrate so the table is created in the app's
+# database (the model is shipped by the gem; the table lives per app).
+class CreateStudioEnumerals < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_enumerals do |t|
+      # `category` groups a fixed set of values (e.g. "pokemon_type"); `key` is
+      # the stable machine value within it (e.g. "fire"). label/color/position
+      # are presentation; metadata (jsonb) carries any category-specific extras.
+      t.string  :category, null: false
+      t.string  :key,      null: false
+      t.string  :label
+      t.string  :color
+      t.integer :position, null: false, default: 0
+      # A sparse, gappy ordinal (100, 200, …) for a domain ranking distinct from
+      # display `position` — e.g. Pokémon types ranked most-common → least-common.
+      # The gaps leave room to insert a value between two ranks without
+      # renumbering. Nullable: not every enumeral is ranked.
+      t.integer :rank
+      t.jsonb   :metadata, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :studio_enumerals, [:category, :key], unique: true
+    add_index :studio_enumerals, [:category, :position]
+    add_index :studio_enumerals, [:category, :rank]
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-22 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -174,6 +174,7 @@ files:
 - app/models/image_cache.rb
 - app/models/session_context.rb
 - app/models/studio/email_delivery.rb
+- app/models/studio/enumeral.rb
 - app/models/studio/link.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
@@ -235,6 +236,7 @@ files:
 - db/migrate/20260614000000_create_studio_email_deliveries.rb
 - db/migrate/20260620000001_create_studio_links.rb
 - db/migrate/20260620000002_allow_null_image_cache_owner.rb
+- db/migrate/20260623130000_create_studio_enumerals.rb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/color_scale.rb