From 0dca85ca8f1fb0c6af723e1af2e631e16b3f9c65 Mon Sep 17 00:00:00 2001
From: "Quintino A. G. Souza" <quin@unicamp.br>
Date: Thu, 19 Mar 2026 08:19:55 -0300
Subject: [PATCH] =?UTF-8?q?Documenta=20sub-m=C3=B3dulo=20site=5Ftools=5Fgr?=
 =?UTF-8?q?oup=5Fhelpers=20e=20atualiza=20README=20principal?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md                                  |  1 +
 modules/site_tools_group_helpers/README.md | 50 ++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 modules/site_tools_group_helpers/README.md

diff --git a/README.md b/README.md
index 0e59eec..35eb125 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ Módulo Drupal com ferramentas utilitárias reutilizáveis para outros módulos
 
 ## Sub-módulos
 
+- **site_tools_group_helpers**: Plugin `EntityReferenceSelection` que restringe campos de referência a grupos aos grupos dos quais o usuário atual é membro, com troca automática para o widget `options_select`. Requer o módulo contrib `group`.
 - **site_tools_msc_2020**: Widget de seleção em cascata (1–3 níveis) para o vocabulário MSC 2020, com carregamento eficiente dos 597 termos via `loadTree()` + consulta direta ao banco.
 - **site_tools_msc_2020_migrate**: Migrations para importação do vocabulário MSC 2020 a partir de CSV.
 
diff --git a/modules/site_tools_group_helpers/README.md b/modules/site_tools_group_helpers/README.md
new file mode 100644
index 0000000..8cf178f
--- /dev/null
+++ b/modules/site_tools_group_helpers/README.md
@@ -0,0 +1,50 @@
+# Site Tools — Group Helpers
+
+Sub-módulo do [Site Tools](../../README.md) com utilitários para integração com o módulo contrib [Group](https://www.drupal.org/project/group).
+
+## Requisitos
+
+- `site_tools`
+- `group` (contrib) ^3.0
+
+## Funcionalidades
+
+### Plugin de seleção: Member groups
+
+Plugin `EntityReferenceSelection` com id `site_tools_group_helpers` que restringe campos de referência à entidade `group` aos grupos dos quais o **usuário atual é membro**, em vez de listar todos os grupos do site.
+
+#### Como usar
+
+No formulário de configuração de um campo `entity_reference` com `target_type: group`, selecione **"Member groups (current user)"** em _Reference type_.
+
+Em YAML de configuração:
+
+```yaml
+handler: 'site_tools_group_helpers'
+handler_settings:
+  target_bundles: null   # null = qualquer tipo de grupo
+```
+
+O módulo também remove a obrigatoriedade de selecionar um tipo de grupo no formulário de configuração do campo, para campos que referenciam `group` — tanto neste handler quanto no handler padrão.
+
+### Troca automática de widget
+
+Ao configurar um campo para usar o handler `site_tools_group_helpers`, o módulo atualiza automaticamente todos os form displays daquele campo para o widget **`options_select`** (caixa de seleção), mais adequado quando o número de opções é pequeno.
+
+Ao reverter para outro handler, o widget é restaurado para `entity_reference_autocomplete`.
+
+## Instalação
+
+```bash
+drush en site_tools_group_helpers
+drush cr
+```
+
+Na instalação, o módulo verifica se há campos existentes já configurados com o handler `site_tools_group_helpers` (por exemplo, após importação de configuração) e aplica o widget `options_select` automaticamente.
+
+## Dependência em outros módulos
+
+```yaml
+dependencies:
+  - site_tools:site_tools_group_helpers
+```